From a8717733ba16711f517132cfd6a485a0fb21cb7f Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Tue, 6 Jan 2026 16:37:21 -0800 Subject: [PATCH] docs: add README and CLAUDE.md, use Pico dropdown for image picker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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
dropdown pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 78 +++++++++++++++++++++++++ src/dev/app.tsx | 96 ++++++++++++++----------------- 3 files changed, 267 insertions(+), 55 deletions(-) create mode 100644 CLAUDE.md create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fd317df --- /dev/null +++ b/CLAUDE.md @@ -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 +- `
` 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 ` instead of `node ` or `ts-node ` +- Use `bun test` instead of `jest` or `vitest` +- Use `bun build ` instead of `webpack` or `esbuild` +- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install` +- Use `bun run + + +``` + +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

Hello, world!

; +} + +root.render(); +``` + +Then, run index.ts + +```sh +bun --hot ./index.ts +``` + +For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..5e2fd4c --- /dev/null +++ b/README.md @@ -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 ( + + + + + + + + + ) +} +``` + +## API + +### `` + +Renders a global `@keyframes` rule. Include once in your ``. + +### `` + +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 `` code for you. diff --git a/src/dev/app.tsx b/src/dev/app.tsx index de3e8e8..2cea435 100644 --- a/src/dev/app.tsx +++ b/src/dev/app.tsx @@ -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 + $("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 = () => (
- -
+ { + const filter = (e.target as HTMLInputElement).value.toLowerCase() + renderImagePicker(filter) + }} + style={{ marginBottom: "0.5rem" }} + /> +