npm package: @fast-preview/core
Description: A minimal library to preview dynamic element
Author: ctlinker
Latest version: 0.1.0

# Preview

`Preview` is a React component that automatically **scales and centers a fixed-format page** (e.g. A4) inside a responsive container.
It’s especially useful for **document previews**, **print layouts**, **PDF-like editors**, or any UI where content must keep a strict page size while adapting to the viewport.

The component exposes a `PreviewContext` to its children, providing access to the rendered element, current scale, and page size.

---

## Features

* 📄 Fixed page formats (A4, presets, or custom sizes)
* 📐 Automatic scaling based on container size
* 🔄 Recomputes scale on window resize
* 🎯 Centers content inside its container
* 🧠 Context API for scale & size awareness in children

---

## Installation

```bash
npm install @fast-preview/core
pnpm add  @fast-preview/core
yarn add  @fast-preview/core
```

---

## Basic Usage

```tsx
import { Preview } from "@fast-preview/core";

export function App() {
  return (
    <div style={{ height: "100vh" }}>
      <Preview format="A4">
        <div>Your page content</div>
      </Preview>
    </div>
  );
}
```

The content will be rendered at **A4 size**, scaled down (or up) to fit the available container.

---

## Props

### `children` (required)

```ts
ReactNode
```

The content to render inside the previewed page.

---

### `format` (optional)

```ts
string | { width: number; height: number }
```

Defines the **target page size**.

#### Preset formats

If a string is provided, it is resolved using `ScalePreset`:

```ts
<Preview format="A4" />
```

If the format is unknown, it falls back to `"A4"`.

#### Custom size

You can provide a custom width/height object:

```ts
<Preview
  format={{
    width: 800,
    height: 1120,
  }}
>
  ...
</Preview>
```

> Units are assumed to be pixels.

⚠️ An error is thrown if the format is invalid.

---

## Behavior

* The component measures its **container size**
* Computes the best scale using `computeScale`
* Applies a CSS `transform: scale(...)` to the page
* Recalculates automatically on window resize
* Children are rendered **only after the page DOM node is mounted**

---

## PreviewContext

Children are wrapped in a `PreviewContext.Provider` once the page element is available.

### Context value

```ts
{
  el: HTMLDivElement;   // the page element
  scale: number;       // current applied scale
  size: { width: number; height: number };
}
```

### Example usage

```tsx
import { useContext } from "react";
import { PreviewContext } from "your-lib";

function DebugInfo() {
  const ctx = useContext(PreviewContext);

  if (!ctx) return null;

  return (
    <div>
      Scale: {ctx.scale}
      <br />
      Size: {ctx.size.width} × {ctx.size.height}
    </div>
  );
}
```

---

## Styling Notes

The component uses inline styles for layout:

* Container:

  * centers content
  * hides overflow
  * light gray background (`#e5e5e5`)
* Page:

  * fixed width/height
  * scaled using `transform: scale(...)`
  * `transform-origin: top left`

You can override styles using the `.preview` and `.projection` class names if needed.

---

## Typical Use Cases

* Print preview UIs
* Resume / invoice / report editors
* PDF-like layout builders
* WYSIWYG document tools

---

## License

Apache License 2