docs: add README and CLAUDE.md, use Pico dropdown for image picker
- README: API docs, usage example, dev tool instructions - CLAUDE.md: architecture notes on Hono JSX, Pico CSS, implementation details - Image picker now uses Pico's <details> dropdown pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
311b91d0c5
commit
a8717733ba
148
CLAUDE.md
Normal file
148
CLAUDE.md
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
# tiny-sprites
|
||||
|
||||
See [README.md](./README.md) for the API and usage documentation.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Hono JSX (not React)
|
||||
|
||||
This project uses Hono's JSX implementation, not React. Key differences:
|
||||
|
||||
- **Server-side**: `hono/jsx` for the Sprite component (renders to HTML strings)
|
||||
- **Client-side**: `hono/jsx/dom` for the dev tool UI (renders to DOM)
|
||||
- **No hooks**: The Sprite component is pure server-side JSX with zero client JavaScript. No `useState`, no `useEffect`. The dev tool uses vanilla JS with a simple mutable `state` object and manual DOM updates via `render()` calls.
|
||||
|
||||
### Dev Tool Styling
|
||||
|
||||
The dev tool uses [Pico CSS](https://picocss.com) for styling:
|
||||
|
||||
- Classless styling - semantic HTML gets styled automatically
|
||||
- `<details class="dropdown">` for the image picker (native open/close, no JS needed)
|
||||
- CSS variables like `var(--pico-primary-background)` for theming
|
||||
|
||||
### Interesting Implementation Details
|
||||
|
||||
**CSS Variables in @keyframes**: Instead of generating unique keyframes per sprite, we define one global keyframe that uses CSS custom properties:
|
||||
|
||||
```css
|
||||
@keyframes sprite {
|
||||
from { background-position: var(--x) var(--y) }
|
||||
to { background-position: var(--ex) var(--y) }
|
||||
}
|
||||
```
|
||||
|
||||
Each sprite just sets `--x`, `--y`, `--ex` as inline styles. This avoids `dangerouslySetInnerHTML` entirely.
|
||||
|
||||
**Frame Detection Algorithm**: The analyzer (`src/dev/analyze.ts`) scans pixel columns to find content regions. It requires a minimum 10px gap between regions to count as separate frames - this handles sprites that have internal empty columns within a frame.
|
||||
|
||||
**Crop Calculation**: For each frame, we find the bounding box of non-transparent pixels, then union all frames' bounds. This gives a consistent crop that works across all animation frames without the sprite "jumping".
|
||||
|
||||
**Canvas Pixel Analysis**: We draw the image to a canvas and use `getImageData()` to read pixel alpha values. The alpha byte is at index `(y * width + x) * 4 + 3` in the flat pixel array.
|
||||
|
||||
---
|
||||
|
||||
Default to using Bun instead of Node.js.
|
||||
|
||||
- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
|
||||
- Use `bun test` instead of `jest` or `vitest`
|
||||
- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
|
||||
- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
|
||||
- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
|
||||
- Use `bunx <package> <command>` instead of `npx <package> <command>`
|
||||
- Bun automatically loads .env, so don't use dotenv.
|
||||
|
||||
## APIs
|
||||
|
||||
- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
|
||||
- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
|
||||
- `Bun.redis` for Redis. Don't use `ioredis`.
|
||||
- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
|
||||
- `WebSocket` is built-in. Don't use `ws`.
|
||||
- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
|
||||
- Bun.$`ls` instead of execa.
|
||||
|
||||
## Testing
|
||||
|
||||
Use `bun test` to run tests.
|
||||
|
||||
```ts#index.test.ts
|
||||
import { test, expect } from "bun:test";
|
||||
|
||||
test("hello world", () => {
|
||||
expect(1).toBe(1);
|
||||
});
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
|
||||
|
||||
Server:
|
||||
|
||||
```ts#index.ts
|
||||
import index from "./index.html"
|
||||
|
||||
Bun.serve({
|
||||
routes: {
|
||||
"/": index,
|
||||
"/api/users/:id": {
|
||||
GET: (req) => {
|
||||
return new Response(JSON.stringify({ id: req.params.id }));
|
||||
},
|
||||
},
|
||||
},
|
||||
// optional websocket support
|
||||
websocket: {
|
||||
open: (ws) => {
|
||||
ws.send("Hello, world!");
|
||||
},
|
||||
message: (ws, message) => {
|
||||
ws.send(message);
|
||||
},
|
||||
close: (ws) => {
|
||||
// handle close
|
||||
}
|
||||
},
|
||||
development: {
|
||||
hmr: true,
|
||||
console: true,
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
|
||||
|
||||
```html#index.html
|
||||
<html>
|
||||
<body>
|
||||
<h1>Hello, world!</h1>
|
||||
<script type="module" src="./frontend.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
With the following `frontend.tsx`:
|
||||
|
||||
```tsx#frontend.tsx
|
||||
import React from "react";
|
||||
import { createRoot } from "react-dom/client";
|
||||
|
||||
// import .css files directly and it works
|
||||
import './index.css';
|
||||
|
||||
const root = createRoot(document.body);
|
||||
|
||||
export default function Frontend() {
|
||||
return <h1>Hello, world!</h1>;
|
||||
}
|
||||
|
||||
root.render(<Frontend />);
|
||||
```
|
||||
|
||||
Then, run index.ts
|
||||
|
||||
```sh
|
||||
bun --hot ./index.ts
|
||||
```
|
||||
|
||||
For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
|
||||
78
README.md
Normal file
78
README.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# tiny-sprites
|
||||
|
||||
A tiny CSS sprite animation component for Hono JSX. Pure CSS animations with zero runtime JavaScript.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add tiny-sprites
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```tsx
|
||||
import { Sprite, SpriteStyles } from "tiny-sprites"
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<html>
|
||||
<head>
|
||||
<SpriteStyles />
|
||||
</head>
|
||||
<body>
|
||||
<Sprite
|
||||
src="/sprites/player.png"
|
||||
frames={4}
|
||||
frameDuration={100}
|
||||
sheetWidth={128}
|
||||
sheetHeight={32}
|
||||
/>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### `<SpriteStyles />`
|
||||
|
||||
Renders a global `@keyframes` rule. Include once in your `<head>`.
|
||||
|
||||
### `<Sprite />`
|
||||
|
||||
Renders an animated sprite.
|
||||
|
||||
| Prop | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `src` | `string` | Yes | | URL to the spritesheet image |
|
||||
| `frames` | `number` | Yes | | Number of frames in the animation |
|
||||
| `frameDuration` | `number` | Yes | | Duration of each frame in milliseconds |
|
||||
| `sheetWidth` | `number` | Yes | | Width of the spritesheet in pixels |
|
||||
| `sheetHeight` | `number` | Yes | | Height of the spritesheet in pixels |
|
||||
| `crop` | `Crop` | No | | Crop each frame to a smaller region |
|
||||
| `scale` | `number` | No | `1` | Scale factor for rendering |
|
||||
| `class` | `string` | No | | CSS class name |
|
||||
| `style` | `string` | No | | Additional inline styles |
|
||||
| `playing` | `boolean` | No | `true` | Whether the animation is playing |
|
||||
|
||||
#### Crop
|
||||
|
||||
```ts
|
||||
type Crop = {
|
||||
x: number // X offset within each frame
|
||||
y: number // Y offset within each frame
|
||||
width: number // Cropped width
|
||||
height: number // Cropped height
|
||||
}
|
||||
```
|
||||
|
||||
## Dev Tool
|
||||
|
||||
A dev server is included to help tune sprite animations and auto-detect frame counts and crop bounds.
|
||||
|
||||
```bash
|
||||
bunx tiny-sprites ./path/to/assets
|
||||
```
|
||||
|
||||
Then open http://localhost:3000 to select spritesheets and configure animations. The tool generates the `<Sprite>` code for you.
|
||||
|
|
@ -157,49 +157,30 @@ const updatePreview = () => {
|
|||
}
|
||||
|
||||
const renderImagePicker = (filter = "") => {
|
||||
const container = $("image-picker")
|
||||
if (state.availableImages.length === 0) {
|
||||
container.style.display = "none"
|
||||
return
|
||||
}
|
||||
const list = $("image-list")
|
||||
const summary = $("image-picker-summary")
|
||||
|
||||
if (state.availableImages.length === 0) return
|
||||
|
||||
// Update summary text
|
||||
summary.textContent = state.relativePath || "Select spritesheet..."
|
||||
|
||||
const filtered = filter
|
||||
? state.availableImages.filter((p) => p.toLowerCase().includes(filter))
|
||||
: state.availableImages
|
||||
|
||||
container.style.display = "block"
|
||||
container.innerHTML = ""
|
||||
|
||||
const list = document.createElement("div")
|
||||
list.style.maxHeight = "300px"
|
||||
list.style.overflowY = "auto"
|
||||
list.style.background = "var(--pico-card-background-color)"
|
||||
list.style.borderRadius = "var(--pico-border-radius)"
|
||||
// Clear existing items (keep the filter input)
|
||||
list.innerHTML = ""
|
||||
|
||||
for (const path of filtered) {
|
||||
const item = document.createElement("div")
|
||||
item.style.cursor = "pointer"
|
||||
item.style.display = "flex"
|
||||
item.style.flexDirection = "column"
|
||||
item.style.alignItems = "center"
|
||||
item.style.gap = "4px"
|
||||
item.style.padding = "12px"
|
||||
item.style.borderBottom = "1px solid var(--pico-muted-border-color)"
|
||||
const li = document.createElement("li")
|
||||
|
||||
if (state.relativePath === path) {
|
||||
item.style.background = "var(--pico-primary-background)"
|
||||
}
|
||||
|
||||
item.onmouseenter = () => {
|
||||
if (state.relativePath !== path) {
|
||||
item.style.background = "var(--pico-secondary-background)"
|
||||
}
|
||||
}
|
||||
item.onmouseleave = () => {
|
||||
if (state.relativePath !== path) {
|
||||
item.style.background = ""
|
||||
}
|
||||
}
|
||||
const link = document.createElement("a")
|
||||
link.href = "#"
|
||||
link.style.display = "flex"
|
||||
link.style.flexDirection = "column"
|
||||
link.style.alignItems = "center"
|
||||
link.style.gap = "4px"
|
||||
|
||||
const img = document.createElement("img")
|
||||
img.src = `/assets/${encodeURIComponent(path).replace(/%2F/g, "/")}`
|
||||
|
|
@ -208,20 +189,24 @@ const renderImagePicker = (filter = "") => {
|
|||
img.style.objectFit = "contain"
|
||||
img.style.imageRendering = "pixelated"
|
||||
|
||||
const label = document.createElement("div")
|
||||
const label = document.createElement("span")
|
||||
label.style.fontSize = "11px"
|
||||
label.style.wordBreak = "break-all"
|
||||
label.style.textAlign = "center"
|
||||
label.textContent = path
|
||||
|
||||
item.appendChild(img)
|
||||
item.appendChild(label)
|
||||
item.onclick = () => loadImageFromPath(path)
|
||||
link.appendChild(img)
|
||||
link.appendChild(label)
|
||||
link.onclick = (e) => {
|
||||
e.preventDefault()
|
||||
loadImageFromPath(path)
|
||||
// Close dropdown
|
||||
$<HTMLDetailsElement>("image-picker").open = false
|
||||
}
|
||||
|
||||
list.appendChild(item)
|
||||
li.appendChild(link)
|
||||
list.appendChild(li)
|
||||
}
|
||||
|
||||
container.appendChild(list)
|
||||
}
|
||||
|
||||
const fetchImages = async () => {
|
||||
|
|
@ -238,19 +223,20 @@ const fetchImages = async () => {
|
|||
const App = () => (
|
||||
<div class="grid">
|
||||
<div>
|
||||
<label>
|
||||
Filter
|
||||
<input
|
||||
type="text"
|
||||
id="filter"
|
||||
placeholder="Search images..."
|
||||
onInput={(e) => {
|
||||
const filter = (e.target as HTMLInputElement).value.toLowerCase()
|
||||
renderImagePicker(filter)
|
||||
}}
|
||||
/>
|
||||
</label>
|
||||
<div id="image-picker" style={{ marginBottom: "1rem", display: "none" }}></div>
|
||||
<input
|
||||
type="search"
|
||||
id="filter"
|
||||
placeholder="Filter spritesheets..."
|
||||
onInput={(e) => {
|
||||
const filter = (e.target as HTMLInputElement).value.toLowerCase()
|
||||
renderImagePicker(filter)
|
||||
}}
|
||||
style={{ marginBottom: "0.5rem" }}
|
||||
/>
|
||||
<details class="dropdown" id="image-picker" style={{ marginBottom: "1rem" }}>
|
||||
<summary id="image-picker-summary">Select spritesheet...</summary>
|
||||
<ul id="image-list" style={{ maxHeight: "400px", overflowY: "auto" }}></ul>
|
||||
</details>
|
||||
<div
|
||||
id="error-message"
|
||||
style={{
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user