@eduvidu/react-autoscale 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,313 @@
+import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Scaling mode used to calculate the scale factor.
+ *
+ * - `'width'`   – scale to fit container width
+ * - `'height'`  – scale to fit container height
+ * - `'contain'` – scale to fit inside the container (default)
+ * - `'cover'`   – scale to fill the container entirely
+ */
+type ScaleMode = 'width' | 'height' | 'contain' | 'cover';
+/**
+ * How to compensate the container size after scaling.
+ *
+ * - `'none'`   – no compensation (default)
+ * - `'width'`  – adjust container width to match scaled content width
+ * - `'height'` – adjust container height to match scaled content height
+ * - `'both'`   – adjust both width and height
+ */
+type CompensationMode = 'none' | 'width' | 'height' | 'both';
+/**
+ * Strategy used to measure an element's natural (unscaled) dimensions.
+ *
+ * - `'scrollSize'`    – uses scrollWidth / scrollHeight (default, avoids scaled size)
+ * - `'boundingRect'`  – uses getBoundingClientRect (may need inverse-transform)
+ * - `'custom'`        – delegates to a user-provided measurer function
+ */
+type MeasurementStrategy = 'scrollSize' | 'boundingRect' | 'custom';
+/** Width × Height pair. */
+interface Dimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * User-provided function to compute a custom scale factor.
+ * Receives the container and content dimensions and must return a numeric
+ * scale value.
+ */
+type CustomCalculator = (container: Readonly<Dimensions>, content: Readonly<Dimensions>) => number;
+/**
+ * User-provided function to measure an element's natural size.
+ * Useful when the default strategies don't accurately capture the content
+ * dimensions (e.g. canvas, SVG, or virtualised lists).
+ */
+type CustomMeasurer = (element: HTMLElement) => Dimensions;
+/** Callback invoked whenever the computed scale changes. */
+type OnScaleChange = (scale: number, details: ScaleChangeDetails) => void;
+/** Detailed information passed to the `onScaleChange` callback. */
+interface ScaleChangeDetails {
+    readonly containerDimensions: Dimensions;
+    readonly contentDimensions: Dimensions;
+    readonly previousScale: number;
+}
+/** Full set of optional configuration for the scaling engine. */
+interface AutoScaleOptions {
+    /**
+     * Scaling strategy.
+     * @default 'contain'
+     */
+    mode?: ScaleMode;
+    /** Minimum allowed scale factor. No default (unclamped). */
+    minScale?: number;
+    /** Maximum allowed scale factor. No default (unclamped). */
+    maxScale?: number;
+    /** Provide a fully custom scale calculator. Overrides `mode`. */
+    customCalculator?: CustomCalculator;
+    /**
+     * When `true`, attach ResizeObserver to the container's **parent** element
+     * instead of the container itself. Useful when the container is sized by an
+     * external layout (e.g. CSS Grid slot).
+     * @default false
+     */
+    observeParent?: boolean;
+    /**
+     * CSS `transform-origin` applied to the scaled content.
+     * @default 'top left'
+     */
+    transformOrigin?: string;
+    /**
+     * Minimum interval (ms) between scale re-calculations.
+     * Uses trailing-edge throttle via `requestAnimationFrame`.
+     */
+    throttle?: number;
+    /**
+     * Debounce delay (ms) for scale re-calculations.
+     * Useful for window-resize-driven layouts.
+     */
+    debounce?: number;
+    /**
+     * Completely disable scaling. When `true` the hook returns `scale: 1` and
+     * does not attach any observers.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Enable debug logging to the console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Adjust the container's dimensions after scaling so surrounding layout
+     * flows correctly around the scaled content.
+     * @default 'none'
+     */
+    compensationMode?: CompensationMode;
+    /** Called whenever the computed scale factor changes. */
+    onScaleChange?: OnScaleChange;
+    /**
+     * Override the measurement strategy for content dimensions.
+     * @default 'scrollSize'
+     */
+    measurementStrategy?: MeasurementStrategy;
+    /**
+     * Custom measurement function, used when `measurementStrategy` is
+     * `'custom'`.
+     */
+    customMeasurer?: CustomMeasurer;
+}
+/** Value returned by the `useAutoScale` hook. */
+interface AutoScaleState {
+    /** Ref to attach to the outer container element. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Ref to attach to the inner content wrapper element. */
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    /** Current computed scale factor. `1` until first measurement. */
+    scale: number;
+    /**
+     * Scaled dimensions of the content (content natural size × scale).
+     * Useful for compensation calculations.
+     */
+    dimensions: Dimensions;
+    /** Measured container dimensions. */
+    containerDimensions: Dimensions;
+    /** Measured natural (unscaled) content dimensions. */
+    contentDimensions: Dimensions;
+    /**
+     * `true` once the first measurement has been performed.
+     * Useful for avoiding flash-of-unstyled-content.
+     */
+    isReady: boolean;
+}
+/** Value provided by `ScaleProvider` to descendant components. */
+interface ScaleContextValue {
+    /** Scale factor of the nearest `AutoScale` ancestor. */
+    scale: number;
+    /** Accumulated scale from all ancestor `AutoScale` components. */
+    parentScale: number;
+    /** Nesting depth (0 = root, no scaling ancestor). */
+    depth: number;
+}
+/**
+ * Props for the `<AutoScale>` component.
+ * All `AutoScaleOptions` + standard `div` attributes.
+ */
+interface AutoScaleProps extends AutoScaleOptions, Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    children?: React.ReactNode;
+    /**
+     * Additional className applied to the inner content wrapper.
+     */
+    contentClassName?: string;
+    /**
+     * Additional style applied to the inner content wrapper.
+     */
+    contentStyle?: React.CSSProperties;
+}
+
+/**
+ * Core hook for auto-scaling content to fit its container.
+ *
+ * Returns refs for the container and content elements, plus the computed
+ * scale factor and dimension information.
+ *
+ * All options are optional — calling `useAutoScale()` with no arguments
+ * produces a fully functional scaling setup using `'contain'` mode.
+ */
+declare function useAutoScale(options?: AutoScaleOptions): AutoScaleState;
+
+/**
+ * Declarative scaling wrapper.
+ *
+ * Usage:
+ * ```tsx
+ * <AutoScale>
+ *   <MyDashboard />
+ * </AutoScale>
+ * ```
+ *
+ * All props are optional. The component renders two nested `<div>` elements:
+ * 1. **Container** (outer) — fills available space, ref'd for size measurement
+ * 2. **Content** (inner) — wraps children, `transform: scale(…)` applied here
+ *
+ * Any HTML `<div>` props not recognised as `AutoScaleOptions` are forwarded
+ * to the outer container `<div>`.
+ */
+declare const AutoScale: react.ForwardRefExoticComponent<AutoScaleProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Provides scale context to descendants.
+ *
+ * When nested, each `ScaleProvider` multiplies its own `scale` with the
+ * inherited `parentScale`, giving any descendant access to the full
+ * accumulated scale factor.
+ */
+declare function ScaleProvider({ scale, children, }: {
+    scale: number;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Read the nearest `ScaleProvider` context.
+ *
+ * Returns `{ scale: 1, parentScale: 1, depth: 0 }` if no provider exists.
+ */
+declare function useScaleContext(): ScaleContextValue;
+
+/**
+ * Pure function — computes a scale factor given container & content dimensions.
+ *
+ * Strategies:
+ * - `'width'`   → container.width / content.width
+ * - `'height'`  → container.height / content.height
+ * - `'contain'` → min(widthScale, heightScale)  — fit inside
+ * - `'cover'`   → max(widthScale, heightScale)  — fill entirely
+ *
+ * If a `customCalculator` is provided it takes priority over `mode`.
+ *
+ * Returns `1` when content has zero width or height (avoids division by zero).
+ */
+declare function calculateScale(container: Readonly<Dimensions>, content: Readonly<Dimensions>, mode?: ScaleMode, customCalculator?: CustomCalculator): number;
+
+/**
+ * Clamp a scale value to `[min, max]`.
+ *
+ * • Both bounds are optional — omitting a bound disables that side.
+ * • Returns `1` for NaN / non-finite input (safe fallback).
+ * • If `min > max` the values are silently swapped.
+ */
+declare function clampScale(scale: number, min?: number, max?: number): number;
+
+/**
+ * Measure an element's **natural (unscaled)** dimensions.
+ *
+ * Strategies:
+ *
+ * - `'scrollSize'` (default) — uses `scrollWidth` / `scrollHeight`.
+ *   These properties report the *intrinsic* content size and are NOT
+ *   affected by CSS `transform: scale(…)`, which is exactly what we need.
+ *
+ * - `'boundingRect'` — uses `getBoundingClientRect()`. Note that this
+ *   DOES reflect transforms, so the caller should ideally read the rect
+ *   *before* applying the scale transform, or compensate manually.
+ *
+ * - `'custom'` — delegates to a user-provided `CustomMeasurer`.
+ */
+declare function measureElement(element: HTMLElement | null, strategy?: MeasurementStrategy, customMeasurer?: CustomMeasurer): Dimensions;
+/**
+ * Measure a container element's **available inner space**.
+ *
+ * Uses `clientWidth` / `clientHeight` which exclude scrollbars but include
+ * padding — this is the usable area for content layout.
+ */
+declare function measureContainer(element: HTMLElement | null): Dimensions;
+
+interface Scheduler {
+    /** Enqueue `callback` to run on the next animation frame. */
+    schedule(callback: () => void): void;
+    /** Cancel any pending animation frame. */
+    cancel(): void;
+    /**
+     * Full cleanup — cancel pending frames and mark the scheduler as
+     * destroyed so no further work is enqueued.
+     */
+    destroy(): void;
+}
+/**
+ * Schedule options for optional throttle / debounce.
+ * At most ONE of `throttle` or `debounce` should be set.
+ */
+interface SchedulerOptions {
+    /** Minimum interval (ms) between executions (throttle). */
+    throttleMs?: number;
+    /** Delay (ms) after the last call before executing (debounce). */
+    debounceMs?: number;
+}
+/**
+ * Create a scheduler instance.
+ *
+ * Design notes:
+ * - Every `schedule()` call cancels the previous pending frame — this
+ *   coalesces rapid-fire `ResizeObserver` callbacks into a single frame.
+ * - Throttle / debounce are implemented *outside* rAF so timing control
+ *   remains predictable.
+ * - `destroy()` must be called on component unmount to prevent leaks.
+ */
+declare function createScheduler(options?: SchedulerOptions): Scheduler;
+
+/**
+ * Returns `true` when running in a browser environment.
+ * Safe to call on server (Next.js SSR / RSC).
+ */
+declare function isBrowser(): boolean;
+/**
+ * Returns `true` when `ResizeObserver` is available.
+ * Older browsers and SSR will return `false`.
+ */
+declare function isResizeObserverSupported(): boolean;
+/**
+ * Composite guard — returns `true` only when both DOM and
+ * `ResizeObserver` are available.
+ */
+declare function canUseDom(): boolean;
+
+export { AutoScale, type AutoScaleOptions, type AutoScaleProps, type AutoScaleState, type CompensationMode, type CustomCalculator, type CustomMeasurer, type Dimensions, type MeasurementStrategy, type OnScaleChange, type ScaleChangeDetails, type ScaleContextValue, type ScaleMode, ScaleProvider, calculateScale, canUseDom, clampScale, createScheduler, isBrowser, isResizeObserverSupported, measureContainer, measureElement, useAutoScale, useScaleContext };

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Scaling mode used to calculate the scale factor.
+ *
+ * - `'width'`   – scale to fit container width
+ * - `'height'`  – scale to fit container height
+ * - `'contain'` – scale to fit inside the container (default)
+ * - `'cover'`   – scale to fill the container entirely
+ */
+type ScaleMode = 'width' | 'height' | 'contain' | 'cover';
+/**
+ * How to compensate the container size after scaling.
+ *
+ * - `'none'`   – no compensation (default)
+ * - `'width'`  – adjust container width to match scaled content width
+ * - `'height'` – adjust container height to match scaled content height
+ * - `'both'`   – adjust both width and height
+ */
+type CompensationMode = 'none' | 'width' | 'height' | 'both';
+/**
+ * Strategy used to measure an element's natural (unscaled) dimensions.
+ *
+ * - `'scrollSize'`    – uses scrollWidth / scrollHeight (default, avoids scaled size)
+ * - `'boundingRect'`  – uses getBoundingClientRect (may need inverse-transform)
+ * - `'custom'`        – delegates to a user-provided measurer function
+ */
+type MeasurementStrategy = 'scrollSize' | 'boundingRect' | 'custom';
+/** Width × Height pair. */
+interface Dimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * User-provided function to compute a custom scale factor.
+ * Receives the container and content dimensions and must return a numeric
+ * scale value.
+ */
+type CustomCalculator = (container: Readonly<Dimensions>, content: Readonly<Dimensions>) => number;
+/**
+ * User-provided function to measure an element's natural size.
+ * Useful when the default strategies don't accurately capture the content
+ * dimensions (e.g. canvas, SVG, or virtualised lists).
+ */
+type CustomMeasurer = (element: HTMLElement) => Dimensions;
+/** Callback invoked whenever the computed scale changes. */
+type OnScaleChange = (scale: number, details: ScaleChangeDetails) => void;
+/** Detailed information passed to the `onScaleChange` callback. */
+interface ScaleChangeDetails {
+    readonly containerDimensions: Dimensions;
+    readonly contentDimensions: Dimensions;
+    readonly previousScale: number;
+}
+/** Full set of optional configuration for the scaling engine. */
+interface AutoScaleOptions {
+    /**
+     * Scaling strategy.
+     * @default 'contain'
+     */
+    mode?: ScaleMode;
+    /** Minimum allowed scale factor. No default (unclamped). */
+    minScale?: number;
+    /** Maximum allowed scale factor. No default (unclamped). */
+    maxScale?: number;
+    /** Provide a fully custom scale calculator. Overrides `mode`. */
+    customCalculator?: CustomCalculator;
+    /**
+     * When `true`, attach ResizeObserver to the container's **parent** element
+     * instead of the container itself. Useful when the container is sized by an
+     * external layout (e.g. CSS Grid slot).
+     * @default false
+     */
+    observeParent?: boolean;
+    /**
+     * CSS `transform-origin` applied to the scaled content.
+     * @default 'top left'
+     */
+    transformOrigin?: string;
+    /**
+     * Minimum interval (ms) between scale re-calculations.
+     * Uses trailing-edge throttle via `requestAnimationFrame`.
+     */
+    throttle?: number;
+    /**
+     * Debounce delay (ms) for scale re-calculations.
+     * Useful for window-resize-driven layouts.
+     */
+    debounce?: number;
+    /**
+     * Completely disable scaling. When `true` the hook returns `scale: 1` and
+     * does not attach any observers.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Enable debug logging to the console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Adjust the container's dimensions after scaling so surrounding layout
+     * flows correctly around the scaled content.
+     * @default 'none'
+     */
+    compensationMode?: CompensationMode;
+    /** Called whenever the computed scale factor changes. */
+    onScaleChange?: OnScaleChange;
+    /**
+     * Override the measurement strategy for content dimensions.
+     * @default 'scrollSize'
+     */
+    measurementStrategy?: MeasurementStrategy;
+    /**
+     * Custom measurement function, used when `measurementStrategy` is
+     * `'custom'`.
+     */
+    customMeasurer?: CustomMeasurer;
+}
+/** Value returned by the `useAutoScale` hook. */
+interface AutoScaleState {
+    /** Ref to attach to the outer container element. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Ref to attach to the inner content wrapper element. */
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    /** Current computed scale factor. `1` until first measurement. */
+    scale: number;
+    /**
+     * Scaled dimensions of the content (content natural size × scale).
+     * Useful for compensation calculations.
+     */
+    dimensions: Dimensions;
+    /** Measured container dimensions. */
+    containerDimensions: Dimensions;
+    /** Measured natural (unscaled) content dimensions. */
+    contentDimensions: Dimensions;
+    /**
+     * `true` once the first measurement has been performed.
+     * Useful for avoiding flash-of-unstyled-content.
+     */
+    isReady: boolean;
+}
+/** Value provided by `ScaleProvider` to descendant components. */
+interface ScaleContextValue {
+    /** Scale factor of the nearest `AutoScale` ancestor. */
+    scale: number;
+    /** Accumulated scale from all ancestor `AutoScale` components. */
+    parentScale: number;
+    /** Nesting depth (0 = root, no scaling ancestor). */
+    depth: number;
+}
+/**
+ * Props for the `<AutoScale>` component.
+ * All `AutoScaleOptions` + standard `div` attributes.
+ */
+interface AutoScaleProps extends AutoScaleOptions, Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    children?: React.ReactNode;
+    /**
+     * Additional className applied to the inner content wrapper.
+     */
+    contentClassName?: string;
+    /**
+     * Additional style applied to the inner content wrapper.
+     */
+    contentStyle?: React.CSSProperties;
+}
+
+/**
+ * Core hook for auto-scaling content to fit its container.
+ *
+ * Returns refs for the container and content elements, plus the computed
+ * scale factor and dimension information.
+ *
+ * All options are optional — calling `useAutoScale()` with no arguments
+ * produces a fully functional scaling setup using `'contain'` mode.
+ */
+declare function useAutoScale(options?: AutoScaleOptions): AutoScaleState;
+
+/**
+ * Declarative scaling wrapper.
+ *
+ * Usage:
+ * ```tsx
+ * <AutoScale>
+ *   <MyDashboard />
+ * </AutoScale>
+ * ```
+ *
+ * All props are optional. The component renders two nested `<div>` elements:
+ * 1. **Container** (outer) — fills available space, ref'd for size measurement
+ * 2. **Content** (inner) — wraps children, `transform: scale(…)` applied here
+ *
+ * Any HTML `<div>` props not recognised as `AutoScaleOptions` are forwarded
+ * to the outer container `<div>`.
+ */
+declare const AutoScale: react.ForwardRefExoticComponent<AutoScaleProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Provides scale context to descendants.
+ *
+ * When nested, each `ScaleProvider` multiplies its own `scale` with the
+ * inherited `parentScale`, giving any descendant access to the full
+ * accumulated scale factor.
+ */
+declare function ScaleProvider({ scale, children, }: {
+    scale: number;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Read the nearest `ScaleProvider` context.
+ *
+ * Returns `{ scale: 1, parentScale: 1, depth: 0 }` if no provider exists.
+ */
+declare function useScaleContext(): ScaleContextValue;
+
+/**
+ * Pure function — computes a scale factor given container & content dimensions.
+ *
+ * Strategies:
+ * - `'width'`   → container.width / content.width
+ * - `'height'`  → container.height / content.height
+ * - `'contain'` → min(widthScale, heightScale)  — fit inside
+ * - `'cover'`   → max(widthScale, heightScale)  — fill entirely
+ *
+ * If a `customCalculator` is provided it takes priority over `mode`.
+ *
+ * Returns `1` when content has zero width or height (avoids division by zero).
+ */
+declare function calculateScale(container: Readonly<Dimensions>, content: Readonly<Dimensions>, mode?: ScaleMode, customCalculator?: CustomCalculator): number;
+
+/**
+ * Clamp a scale value to `[min, max]`.
+ *
+ * • Both bounds are optional — omitting a bound disables that side.
+ * • Returns `1` for NaN / non-finite input (safe fallback).
+ * • If `min > max` the values are silently swapped.
+ */
+declare function clampScale(scale: number, min?: number, max?: number): number;
+
+/**
+ * Measure an element's **natural (unscaled)** dimensions.
+ *
+ * Strategies:
+ *
+ * - `'scrollSize'` (default) — uses `scrollWidth` / `scrollHeight`.
+ *   These properties report the *intrinsic* content size and are NOT
+ *   affected by CSS `transform: scale(…)`, which is exactly what we need.
+ *
+ * - `'boundingRect'` — uses `getBoundingClientRect()`. Note that this
+ *   DOES reflect transforms, so the caller should ideally read the rect
+ *   *before* applying the scale transform, or compensate manually.
+ *
+ * - `'custom'` — delegates to a user-provided `CustomMeasurer`.
+ */
+declare function measureElement(element: HTMLElement | null, strategy?: MeasurementStrategy, customMeasurer?: CustomMeasurer): Dimensions;
+/**
+ * Measure a container element's **available inner space**.
+ *
+ * Uses `clientWidth` / `clientHeight` which exclude scrollbars but include
+ * padding — this is the usable area for content layout.
+ */
+declare function measureContainer(element: HTMLElement | null): Dimensions;
+
+interface Scheduler {
+    /** Enqueue `callback` to run on the next animation frame. */
+    schedule(callback: () => void): void;
+    /** Cancel any pending animation frame. */
+    cancel(): void;
+    /**
+     * Full cleanup — cancel pending frames and mark the scheduler as
+     * destroyed so no further work is enqueued.
+     */
+    destroy(): void;
+}
+/**
+ * Schedule options for optional throttle / debounce.
+ * At most ONE of `throttle` or `debounce` should be set.
+ */
+interface SchedulerOptions {
+    /** Minimum interval (ms) between executions (throttle). */
+    throttleMs?: number;
+    /** Delay (ms) after the last call before executing (debounce). */
+    debounceMs?: number;
+}
+/**
+ * Create a scheduler instance.
+ *
+ * Design notes:
+ * - Every `schedule()` call cancels the previous pending frame — this
+ *   coalesces rapid-fire `ResizeObserver` callbacks into a single frame.
+ * - Throttle / debounce are implemented *outside* rAF so timing control
+ *   remains predictable.
+ * - `destroy()` must be called on component unmount to prevent leaks.
+ */
+declare function createScheduler(options?: SchedulerOptions): Scheduler;
+
+/**
+ * Returns `true` when running in a browser environment.
+ * Safe to call on server (Next.js SSR / RSC).
+ */
+declare function isBrowser(): boolean;
+/**
+ * Returns `true` when `ResizeObserver` is available.
+ * Older browsers and SSR will return `false`.
+ */
+declare function isResizeObserverSupported(): boolean;
+/**
+ * Composite guard — returns `true` only when both DOM and
+ * `ResizeObserver` are available.
+ */
+declare function canUseDom(): boolean;
+
+export { AutoScale, type AutoScaleOptions, type AutoScaleProps, type AutoScaleState, type CompensationMode, type CustomCalculator, type CustomMeasurer, type Dimensions, type MeasurementStrategy, type OnScaleChange, type ScaleChangeDetails, type ScaleContextValue, type ScaleMode, ScaleProvider, calculateScale, canUseDom, clampScale, createScheduler, isBrowser, isResizeObserverSupported, measureContainer, measureElement, useAutoScale, useScaleContext };