@eduvidu/react-autoscale 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-23
+
+### Added
+
+- `useAutoScale()` hook — zero-config, container-aware scaling with ResizeObserver
+- `<AutoScale>` component — declarative wrapper with full prop forwarding
+- `ScaleProvider` / `useScaleContext()` — nested scale context for deep trees
+- Scale modes: `width`, `height`, `contain`, `cover`, custom calculator
+- Measurement strategies: `scrollSize`, `boundingRect`, custom measurer
+- `clampScale()` — safe clamping with edge-case handling
+- `calculateScale()` — pure, framework-agnostic scale calculation
+- `createScheduler()` — rAF-batched scheduling with throttle/debounce
+- `isBrowser()` / `canUseDom()` — SSR environment guards
+- Compensation modes: `none`, `width`, `height`, `both`
+- `onScaleChange` callback with full dimension details
+- `disabled` / `debug` options
+- Dual ESM + CJS builds with TypeScript declarations
+- Full sourcemaps
+- 69 unit tests with 94%+ coverage
+- Zero runtime dependencies
+- Tree-shakeable exports
+- ~3KB gzipped ESM bundle

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eduvidu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,436 @@
+# @eduvidu/react-autoscale
+
+A production-ready, enterprise-grade universal scaling engine for React.
+
+**Zero config • SSR-safe • Tree-shakeable • ~3KB gzipped**
+
+[![npm](https://img.shields.io/npm/v/@eduvidu/react-autoscale)](https://www.npmjs.com/package/@eduvidu/react-autoscale)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@eduvidu/react-autoscale)](https://bundlephobia.com/package/@eduvidu/react-autoscale)
+[![license](https://img.shields.io/npm/l/@eduvidu/react-autoscale)](LICENSE)
+
+---
+
+## Features
+
+- 🪶 **~3KB gzipped** — zero runtime dependencies
+- ⚡ **ResizeObserver + rAF batching** — no layout thrashing
+- 🔒 **SSR-safe** — works with Next.js (App Router & Pages Router)
+- 🌳 **Tree-shakeable** — import only what you use
+- 🎯 **Zero config** — works with zero props out of the box
+- 📐 **5 scale modes** — `width`, `height`, `contain`, `cover`, custom
+- 🪆 **Nested scaling** — context-aware deep nesting support
+- 🔌 **Plugin-style** — custom calculators, custom measurers
+- 📦 **Dual ESM + CJS** — with full TypeScript declarations
+
+---
+
+## Installation
+
+```bash
+npm install @eduvidu/react-autoscale
+# or
+yarn add @eduvidu/react-autoscale
+# or
+pnpm add @eduvidu/react-autoscale
+```
+
+**Peer dependencies:** `react >= 16.8.0`
+
+---
+
+## Compatibility
+
+| React Version | Status       | Notes                                      |
+| ------------- | ------------ | ------------------------------------------ |
+| 16.8+         | ✅ Supported | Hooks baseline                             |
+| 17            | ✅ Tested    | Full support                               |
+| 18            | ✅ Tested    | StrictMode safe, concurrent rendering safe |
+| 19            | ✅ Tested    | Full support                               |
+
+**StrictMode:** The library is fully compatible with React 18+ StrictMode. In development mode, React double-invokes effects to catch bugs — `useAutoScale` correctly creates and tears down `ResizeObserver` and the rAF scheduler in each mount/unmount cycle with no duplicate observers or memory leaks.
+
+**Concurrent rendering:** The library uses only stable React public APIs (`useState`, `useRef`, `useCallback`, `useEffect`, `useMemo`, `useContext`, `forwardRef`, `useImperativeHandle`, `createContext`). No internal or private React APIs are used. No assumptions that break under concurrent rendering.
+
+**SSR:** All browser APIs (`window`, `document`, `ResizeObserver`, `requestAnimationFrame`) are guarded behind `isBrowser()` / `isResizeObserverSupported()` checks. The library renders safely in Next.js App Router, Pages Router, and any Node.js SSR environment — returning `scale: 1` and `isReady: false` until the client hydrates.
+
+---
+
+## Quick Start
+
+### Component API
+
+```tsx
+import { AutoScale } from '@eduvidu/react-autoscale';
+
+function Dashboard() {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <AutoScale>
+        <div style={{ width: 1920, height: 1080 }}>
+          {/* Your fixed-size content scales to fit */}
+          <DashboardGrid />
+        </div>
+      </AutoScale>
+    </div>
+  );
+}
+```
+
+### Hook API
+
+```tsx
+import { useAutoScale } from '@eduvidu/react-autoscale';
+
+function ScalableTable() {
+  const { containerRef, contentRef, scale, isReady } = useAutoScale({
+    mode: 'width',
+  });
+
+  return (
+    <div ref={containerRef} style={{ width: '100%', height: '100%' }}>
+      <div
+        ref={contentRef}
+        style={{
+          transform: `scale(${scale})`,
+          transformOrigin: 'top left',
+          opacity: isReady ? 1 : 0,
+        }}
+      >
+        <LargeTable />
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `<AutoScale>`
+
+Declarative scaling wrapper. All props optional.
+
+| Prop                  | Type                                          | Default        | Description                                 |
+| --------------------- | --------------------------------------------- | -------------- | ------------------------------------------- |
+| `mode`                | `'width' \| 'height' \| 'contain' \| 'cover'` | `'contain'`    | Scale strategy                              |
+| `minScale`            | `number`                                      | —              | Minimum scale factor                        |
+| `maxScale`            | `number`                                      | —              | Maximum scale factor                        |
+| `customCalculator`    | `(container, content) => number`              | —              | Custom scale function (overrides mode)      |
+| `observeParent`       | `boolean`                                     | `false`        | Observe parent element instead of container |
+| `transformOrigin`     | `string`                                      | `'top left'`   | CSS transform-origin                        |
+| `throttle`            | `number`                                      | —              | Min interval (ms) between recalculations    |
+| `debounce`            | `number`                                      | —              | Debounce delay (ms)                         |
+| `disabled`            | `boolean`                                     | `false`        | Disable scaling entirely                    |
+| `debug`               | `boolean`                                     | `false`        | Log measurements to console                 |
+| `compensationMode`    | `'none' \| 'width' \| 'height' \| 'both'`     | `'none'`       | Adjust container size after scaling         |
+| `onScaleChange`       | `(scale, details) => void`                    | —              | Called when scale changes                   |
+| `measurementStrategy` | `'scrollSize' \| 'boundingRect' \| 'custom'`  | `'scrollSize'` | How to measure content size                 |
+| `customMeasurer`      | `(element) => { width, height }`              | —              | Custom measurement function                 |
+| `contentClassName`    | `string`                                      | —              | Class for inner content wrapper             |
+| `contentStyle`        | `CSSProperties`                               | —              | Style for inner content wrapper             |
+
+All standard `<div>` attributes (className, id, data-\*, onClick, etc.) are forwarded to the outer container.
+
+### `useAutoScale(options?)`
+
+Returns:
+
+| Property              | Type                        | Description                           |
+| --------------------- | --------------------------- | ------------------------------------- |
+| `containerRef`        | `RefObject<HTMLDivElement>` | Attach to container element           |
+| `contentRef`          | `RefObject<HTMLDivElement>` | Attach to content element             |
+| `scale`               | `number`                    | Current scale factor (default `1`)    |
+| `dimensions`          | `{ width, height }`         | Scaled content dimensions             |
+| `containerDimensions` | `{ width, height }`         | Container dimensions                  |
+| `contentDimensions`   | `{ width, height }`         | Natural (unscaled) content dimensions |
+| `isReady`             | `boolean`                   | `true` after first measurement        |
+
+### `ScaleProvider` / `useScaleContext()`
+
+For nested scaling awareness:
+
+```tsx
+import { useScaleContext } from '@eduvidu/react-autoscale';
+
+function NestedWidget() {
+  const { scale, parentScale, depth } = useScaleContext();
+  // scale = this level's scale
+  // parentScale = accumulated scale from all ancestors
+  // depth = nesting level (0 = no AutoScale ancestor)
+}
+```
+
+### Core Utilities
+
+These are framework-agnostic and can be used independently:
+
+```ts
+import {
+  calculateScale,
+  clampScale,
+  measureElement,
+  measureContainer,
+  createScheduler,
+  isBrowser,
+  canUseDom,
+} from '@eduvidu/react-autoscale';
+```
+
+---
+
+## Examples
+
+### Nested Scaling
+
+```tsx
+<AutoScale mode="contain">
+  <div style={{ width: 1920, height: 1080 }}>
+    <Header />
+    <AutoScale mode="width">
+      <DataTable columns={50} />
+    </AutoScale>
+    <Footer />
+  </div>
+</AutoScale>
+```
+
+### Custom Scale Calculator
+
+```tsx
+<AutoScale
+  customCalculator={(container, content) => {
+    // Scale to 80% of container width
+    return (container.width * 0.8) / content.width;
+  }}
+>
+  <WidgetPanel />
+</AutoScale>
+```
+
+### Scale Change Tracking
+
+```tsx
+<AutoScale
+  onScaleChange={(scale, { previousScale, containerDimensions }) => {
+    analytics.track('scale_changed', { scale, previousScale });
+  }}
+>
+  <Dashboard />
+</AutoScale>
+```
+
+### Compensation Mode
+
+When you need surrounding content to flow around the scaled content:
+
+```tsx
+<AutoScale compensationMode="height" mode="width">
+  {/* Container height adjusts to match scaled content height */}
+  <FixedWidthContent />
+</AutoScale>
+```
+
+### With Clamping
+
+```tsx
+<AutoScale minScale={0.5} maxScale={2}>
+  <ResponsivePanel />
+</AutoScale>
+```
+
+### Debounced Scaling
+
+```tsx
+<AutoScale debounce={150}>
+  <ExpensiveChart />
+</AutoScale>
+```
+
+---
+
+## Next.js Usage
+
+Works out of the box with both App Router and Pages Router:
+
+```tsx
+// app/dashboard/page.tsx (App Router)
+'use client';
+
+import { AutoScale } from '@eduvidu/react-autoscale';
+
+export default function DashboardPage() {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <AutoScale>
+        <div style={{ width: 1920, height: 1080 }}>
+          <DashboardContent />
+        </div>
+      </AutoScale>
+    </div>
+  );
+}
+```
+
+> **Note:** Since `AutoScale` uses `useRef` and `useEffect`, it must be a client component. Add `'use client'` at the top of the file when using App Router.
+
+---
+
+## Vite Usage
+
+```tsx
+// src/App.tsx
+import { AutoScale } from '@eduvidu/react-autoscale';
+
+function App() {
+  return (
+    <AutoScale style={{ width: '100vw', height: '100vh' }}>
+      <div style={{ width: 1440, height: 900 }}>
+        <MyApp />
+      </div>
+    </AutoScale>
+  );
+}
+```
+
+---
+
+## Performance Notes
+
+### How it works
+
+1. **ResizeObserver** watches the container for size changes
+2. **rAF batching** coalesces rapid resize events into a single frame
+3. **Epsilon comparison** (`1e-4`) skips React re-renders when scale hasn't meaningfully changed
+4. **Stable refs** prevent unnecessary observer re-creation
+5. **transform: scale()** is GPU-accelerated — no reflow triggered
+
+### What we avoid
+
+- ❌ `zoom` property (inconsistent cross-browser)
+- ❌ Measuring scaled dimensions (leads to feedback loops)
+- ❌ Layout thrashing (no interleaved reads/writes)
+- ❌ ResizeObserver loop errors (rAF wrapping)
+- ❌ Memory leaks (observer disconnect + scheduler destroy on unmount)
+
+---
+
+## Anti-Patterns
+
+```tsx
+// ❌ BAD: Don't set explicit width/height on the AutoScale container
+// (it needs to fill available space to calculate scale)
+<AutoScale style={{ width: 500, height: 300 }}>...</AutoScale>
+
+// ✅ GOOD: Let it fill its parent
+<div style={{ width: 500, height: 300 }}>
+  <AutoScale>...</AutoScale>
+</div>
+```
+
+```tsx
+// ❌ BAD: Don't apply transform to children manually
+<AutoScale>
+  <div style={{ transform: 'scale(2)' }}>...</div>
+</AutoScale>
+
+// ✅ GOOD: Let AutoScale handle all transforms
+<AutoScale>
+  <div>...</div>
+</AutoScale>
+```
+
+---
+
+## Competitor Comparison
+
+| Feature            | @eduvidu/react-autoscale                  | react-fit | react-zoom-pan-pinch |
+| ------------------ | ----------------------------------------- | --------- | -------------------- |
+| Bundle (gzip)      | **~3KB**                                  | ~8KB      | ~45KB                |
+| Dependencies       | **0**                                     | Multiple  | Multiple             |
+| Scale modes        | **5** (width/height/contain/cover/custom) | 1         | Pan/zoom only        |
+| SSR safe           | **✅**                                    | ❌        | ❌                   |
+| Tree-shakeable     | **✅**                                    | ❌        | ❌                   |
+| rAF batching       | **✅**                                    | ❌        | Partial              |
+| Nested scaling     | **✅**                                    | ❌        | ❌                   |
+| Zero config        | **✅**                                    | ❌        | ❌                   |
+| Plugin calculators | **✅**                                    | ❌        | ❌                   |
+| Compensation modes | **✅**                                    | ❌        | ❌                   |
+
+---
+
+## Known Limitations
+
+1. **Content must have intrinsic size** — the content children should have explicit or natural dimensions for measurement to work. Flexbox/grid children that stretch may report incorrect sizes.
+
+2. **CSS transitions on scaled content** — adding `transition: transform` to the content div may cause visual jitter during rapid resizing.
+
+3. **Hidden containers** — if the container is `display: none` at mount time, the initial measurement will be `0`. Scale will recalculate when the container becomes visible.
+
+4. **iframe content** — content inside iframes cannot be measured by the parent's ResizeObserver.
+
+---
+
+## Publishing
+
+```bash
+# 1. Build
+npm run build
+
+# 2. Test
+npm test
+
+# 3. Type-check
+npm run typecheck
+
+# 4. Dry run
+npm pack --dry-run
+
+# 5. Publish
+npm publish --access public
+```
+
+---
+
+## Development
+
+```bash
+# Install
+npm install
+
+# Dev mode (watch)
+npm run dev
+
+# Test (watch)
+npm run test:watch
+
+# Test with coverage
+npm run test:coverage
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+
+# Build
+npm run build
+```
+
+---
+
+## Future Roadmap
+
+- [ ] `useAutoScaleTransition` — animated scale transitions
+- [ ] `direction: 'rtl'` support for transform-origin
+- [ ] Resize breakpoint callbacks
+- [ ] Performance observer integration
+- [ ] React Native support (experimental)
+- [ ] Storybook examples
+- [ ] Playground website
+
+---
+
+## License
+
+[MIT](LICENSE) © eduvidu