Initial Commit
This commit is contained in:
92
packages/foundation/data/react-packer/README.md
Normal file
92
packages/foundation/data/react-packer/README.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# @suaveplan/react-packer - React 19 companion for @suaveplan/packer-browser — usePackedResource, usePackedImage, usePackedAudio, usePackedVideo, usePackedFont hooks plus PackedResourceProvider context. Consumes a real PackedResourceManager; React is a peer dep so non-React consumers never pay the cost.
|
||||
|
||||
React 19 companion for `@suaveplan/packer-browser`. Ships
|
||||
`usePackedResource`, `usePackedImage`, `usePackedAudio`,
|
||||
`usePackedVideo`, and `usePackedFont` hooks plus a
|
||||
`PackedResourceProvider` context, so applications can consume packed
|
||||
asset archives from React components without `@suaveplan/packer-browser`
|
||||
having to ship React as a runtime dep.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
|
||||
- [use-packed-audio](./src/hooks/use-packed-audio/use-packed-audio.md) — `usePackedAudio` is the audio analogue of `usePackedImage`. It binds a packed audio asset URL to a React component's li…
|
||||
- [use-packed-audio](./src/hooks/use-packed-audio/use-packed-audio.md) — `usePackedAudio` is the audio analogue of `usePackedImage`. It binds a packed audio asset URL to a React component's li…
|
||||
- [use-packed-font](./src/hooks/use-packed-font/use-packed-font.md) — `usePackedFont` loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
|
||||
- [use-packed-font](./src/hooks/use-packed-font/use-packed-font.md) — `usePackedFont` loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
|
||||
- [use-packed-image](./src/hooks/use-packed-image/use-packed-image.md) — `usePackedImage` is a thin wrapper around `usePackedResource` that pre-fills sensible defaults for image assets: cachin…
|
||||
- [use-packed-image](./src/hooks/use-packed-image/use-packed-image.md) — `usePackedImage` is a thin wrapper around `usePackedResource` that pre-fills sensible defaults for image assets: cachin…
|
||||
- [use-packed-resource](./src/hooks/use-packed-resource/use-packed-resource.md) — `usePackedResource` is the foundation hook of `@suaveplan/react-packer`. It binds a packed-archive virtual URL (e.g. `/…
|
||||
- [use-packed-resource](./src/hooks/use-packed-resource/use-packed-resource.md) — `usePackedResource` is the foundation hook of `@suaveplan/react-packer`. It binds a packed-archive virtual URL (e.g. `/…
|
||||
- [use-packed-video](./src/hooks/use-packed-video/use-packed-video.md) — `usePackedVideo` binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
|
||||
- [use-packed-video](./src/hooks/use-packed-video/use-packed-video.md) — `usePackedVideo` binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
|
||||
- [packed-resource-provider](./src/provider/packed-resource-provider/packed-resource-provider.md) — `PackedResourceProvider` lets a React tree explicitly inject a `PackedResourceManager` from `@suaveplan/packer-browser`…
|
||||
- [packed-resource-provider](./src/provider/packed-resource-provider/packed-resource-provider.md) — `PackedResourceProvider` lets a React tree explicitly inject a `PackedResourceManager` from `@suaveplan/packer-browser`…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/react-packer @suaveplan/packer-browser
|
||||
```
|
||||
|
||||
`react` and `react-dom` (≥ 19.0.0) are peer dependencies — the package
|
||||
does not bundle them.
|
||||
|
||||
## Quick start
|
||||
|
||||
```tsx
|
||||
import { createPackedResourceManager } from "@suaveplan/packer-browser";
|
||||
import { PackedResourceProvider, usePackedImage } from "@suaveplan/react-packer";
|
||||
|
||||
const manager = createPackedResourceManager();
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<PackedResourceProvider value={{ manager }}>
|
||||
<Logo />
|
||||
</PackedResourceProvider>
|
||||
);
|
||||
}
|
||||
|
||||
function Logo() {
|
||||
const { url, loading, error } = usePackedImage("/assets/logo.packed");
|
||||
if (loading) return <div className="logo logo--loading" />;
|
||||
if (error !== null) return <div className="logo logo--error" />;
|
||||
return url !== null ? <img alt="logo" src={url} /> : null;
|
||||
}
|
||||
```
|
||||
|
||||
If you do not mount a `PackedResourceProvider`, hooks fall back to the
|
||||
singleton at `@suaveplan/packer-browser/singleton`. Adopters that prefer
|
||||
zero-config get a working manager for free; adopters that want explicit
|
||||
lifecycle (tests, SSR, multi-tenant apps) mount a provider and skip the
|
||||
singleton entirely.
|
||||
|
||||
## Features
|
||||
|
||||
- Five hooks: `usePackedResource` (generic), `usePackedImage`,
|
||||
`usePackedAudio`, `usePackedVideo`, `usePackedFont`.
|
||||
- React 19 context provider for explicit `PackedResourceManager` and
|
||||
`MessageResolver` injection.
|
||||
- `AbortSignal` honored throughout — pre-aborted signals short-circuit,
|
||||
unmount cancels the in-flight load, and changing the packed URL
|
||||
aborts the previous one.
|
||||
- Stable error registry — `REACT_PACKER_CODES` + `ReactPackerError`
|
||||
branded subclass over `@suaveplan/error`.
|
||||
- `cleanup` releases the cached entry on unmount so the manager's LRU
|
||||
can evict.
|
||||
|
||||
## Modules
|
||||
|
||||
- [`src/error-codes/error-codes.md`](./src/error-codes/error-codes.md)
|
||||
- [`src/types/react-packer.types.md`](./src/types/react-packer.types.md)
|
||||
- [`src/provider/packed-resource-provider/packed-resource-provider.md`](./src/provider/packed-resource-provider/packed-resource-provider.md)
|
||||
- [`src/hooks/use-packed-resource/use-packed-resource.md`](./src/hooks/use-packed-resource/use-packed-resource.md)
|
||||
- [`src/hooks/use-packed-image/use-packed-image.md`](./src/hooks/use-packed-image/use-packed-image.md)
|
||||
- [`src/hooks/use-packed-audio/use-packed-audio.md`](./src/hooks/use-packed-audio/use-packed-audio.md)
|
||||
- [`src/hooks/use-packed-video/use-packed-video.md`](./src/hooks/use-packed-video/use-packed-video.md)
|
||||
- [`src/hooks/use-packed-font/use-packed-font.md`](./src/hooks/use-packed-font/use-packed-font.md)
|
||||
|
||||
Reference in New Issue
Block a user