# Loaders

A few dots that change shape while an answer is on its way.

Package: @reuse-sh/loaders

## Principles

These are the rules to keep when you adapt this library. The code is one way to keep them. An adaptation on any framework must keep every one.

- Move dots, not frames. Between figures each dot travels to its new place instead of popping.

- Show every figure in turn. The default sequence shows each figure once per round and never the same one twice running.

- Draw in the text color. The canvas takes its color from the surrounding text, so it fits any theme.

- Stop when unseen. The clock pauses offscreen and in hidden tabs, and reduced motion shows a still figure.

- Stay silent unless labeled. The dots are decorative, and a label turns them into a status for screen readers.

- Give the canvas back. Destroy stops the clock and restores the canvas.

## Install

```bash
npm install @reuse-sh/loaders
```

## Integration notes

- The default sequence moves through every figure. figureConfig repeats one.

- ThinkingDots is decorative unless you pass a label, which makes it a status for screen readers.

- Pick a figure or write the sequence in code. There is nothing to configure elsewhere.

## API

- `createThinkingDots(canvas, options?)`: Draws the dots on a canvas in its text color. Options: size, config and seed.

- `play(), pause(), setConfig(config), destroy()`: Controls the animation and swaps the figure or sequence.

- `figureConfig(name), figureNames`: A config that repeats one figure, and the list of figure names.

- `THINKING_DOTS`: The default config, which moves through every figure.

- `createTimeline(config, seed), sampleDot(timeline, dot, time)`: The timeline and sampler the canvas uses, for your own renderer.

- `ThinkingDots`: The React component. Pass a label to announce it as a status.

## Browser JavaScript

```js
import {
  createThinkingDots,
  figureConfig,
} from "@reuse-sh/loaders";

const loader = createThinkingDots(canvas, {
  size: 32,
  config: figureConfig("triangle-turn"),
});

// Later, when the answer arrives
loader.destroy();
```

## React

```tsx
import { ThinkingDots } from "@reuse-sh/loaders/react";
import "@reuse-sh/loaders/styles.css";

<ThinkingDots size={24} label="Preparing your answer" />
```

## Agent workflow

1. Inspect the project and read the installed package's types and stylesheet.

2. Reuse the native controller. Use the React adapter only in a React surface.

3. Adapt styles and data connections to the project. Keep every principle above. Do not recreate the gesture or state engine.

4. Connect destroy and unsubscribe callbacks to the owner lifecycle.

5. Verify keyboard access, pointer/touch behavior, resize, empty/one-item states, errors, reduced motion, and teardown where applicable.

6. Report the actual checks and remaining browser/device limits.

## Source

https://github.com/reuse-sh/reuse/tree/main/packages/loaders/src

License: MIT for original library code. Preserve dependency and asset license notices.