@markmiro/hairy 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# hairy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fur for your buttons. `hairy` draws an animated coat of hair behind a button's label, on the GPU with WebGL2. The fur rises on hover, poofs up on click, and bends as the pointer brushes across it.
+
+```sh
+npm i @markmiro/hairy
+```
+
+Or install it straight from GitHub. Each push to `main` builds the package onto the `release` branch, and each new version is tagged:
+
+```jsonc
+{
+  "dependencies": {
+    "@markmiro/hairy": "github:markmiro/hairy#v0.1.0", // a pinned version
+    // "@markmiro/hairy": "github:markmiro/hairy#semver:^0.1.0", // a version range
+    // "@markmiro/hairy": "github:markmiro/hairy#release", // the latest build of main
+  }
+}
+```
+
+## Use
+
+```js
+import { hairy } from "@markmiro/hairy"
+
+const fur = hairy(document.querySelector("#adopt"), {
+  preset: "plush",
+  color: "#ff4d70",
+  label: "auto",
+})
+```
+
+It works on a button you already have: no wrapper, and no global CSS. While the fur is mounted, `hairy` sets the element's `position` (if it's static), `isolation`, `background-color`, with `label` its `color`, and with a halo behind the label its `text-shadow`. `fur.destroy()` puts them back.
+
+### React
+
+```tsx
+import { useHairy } from "@markmiro/hairy/react"
+
+function AdoptButton() {
+  const ref = useHairy<HTMLButtonElement>({ preset: "plush", color: "#ff4d70", label: "auto" })
+  return <button ref={ref}>Adopt a cat</button>
+}
+```
+
+## Options
+
+| Option | |
+| --- | --- |
+| `preset` | `"plush"` (default), `"teddy"`, `"fluffy"`, `"fuzzy"`, `"shaggy"`, `"mane"`, and the fun ones: `"tinsel"`, `"coil"`, `"mustache"`, `"bristle"` |
+| `color` | The fur's color, any CSS color. Defaults to the element's background color. |
+| `label` | `"auto"` picks a readable label color by APCA contrast; a CSS color sets it; leave it out to keep the element's own. On a pattern, `"auto"` looks for a color that reads on the ground and the markings alike. |
+| `scale` | Hair size. At 2 the hairs are twice as long and thick, and fewer. In em, like `"1em"`, it follows the element's font size (see below). Defaults to the `--hairy-scale` CSS variable, or 1. |
+| `translate` | Moves the fur down, in CSS px; below 0 moves it up. Hair combs down, so it hangs further below the element than it reaches above it, and the label can look high: a few px up, like `-4`, centers the fur on it. Defaults to 0. |
+| `wideGamut` | Draw in Display P3 on screens that support it. Defaults to `true`. |
+| `pixelRatio` | Canvas pixels per CSS pixel. Defaults to the screen's, up to 2. Set it higher to bake large images. |
+
+### Hair that follows the font size
+
+By default the hairs are sized in CSS px, so they stay the same size when a button shrinks. Give `scale` in em and they're sized from the element's font size instead, where 16px is `1em`:
+
+```js
+hairy(button, { scale: "1em" })   // a 16px button gets the default hair, a 32px one hair twice the size
+hairy(button, { scale: "1.5em" }) // half as big again, at any font size
+```
+
+The number before `em` is the multiplier, so `"1em"` at a 16px font is the same as `scale: 1`. When the font size changes, say a smaller one on phones, the hairs follow, along with how far they reach (`fur.reach`) and the room the canvas leaves for them. They're measured whenever the element resizes, which a font-size change does unless the element's size is fixed.
+
+`scale` can also come from CSS, with the `--hairy-scale` variable on the element or an ancestor. It takes the same values, a number or an em value, and `scale` overrides it:
+
+```css
+.hero { --hairy-scale: 1.5em; }
+```
+
+Every look and motion setting is grouped, and overrides the preset's value:
+
+```js
+hairy(button, {
+  preset: "fluffy",
+  shade: { lightness, shadows, highlights, vividness },
+  shine: { amount, position, spread, edgeShadow },
+  hair: { density, length, thickness, taper, softness, curl, droop, lengthVariation, messiness, fuzz, distance, type, typeAmount, tightness, end },
+  material: { type, amount },
+  pattern: { type, colors, scale },
+  halo: { when, shade, size, strength },
+  glitter: { density, size, sizeVariation },
+  rest: { static },
+  hover: { static, stretch, lightness, sway, speed, damping },
+  leave: { speed, damping },
+  click: { static, stretch, lightness, riseSpeed, riseDamping, hold, fallSpeed, fallDamping },
+  brush: { amount, speed, damping },
+})
+```
+
+`static` is how far the hairs stand up: on their own at rest, then further on hover, then further still on a click. The playground lets you tune all of these visually and copies the code for you.
+
+A few options pick from a list instead of taking a number:
+
+| Option | |
+| --- | --- |
+| `hair.type` | `"straight"` (default), `"wavy"`, `"curly"` (coils that loop back on themselves) or `"frizzy"` (random kinks and flyaways). `typeAmount` sets how strong they are and `tightness` how many fit along each hair. |
+| `hair.end` | `"round"` (default), `"sharp"` (narrows to a point) or `"square"` (cut straight across). |
+| `material.type` | `"natural"` (default) or `"glitter"` (flakes that twinkle as the fur moves). `material.amount` sets how bright the flashes are, and `glitter` sets how many flakes there are, how big, and how much their sizes differ. |
+| `pattern.type` | `"none"` (default), `"zebra"`, `"tiger"`, `"dalmatian"`, `"leopard"` or `"giraffe"`: a coat pattern. Each hair takes the color where it grows, so the markings have soft, hairy edges. `pattern.scale` sets how big the stripes, spots or patches are (1 the usual size). |
+| `pattern.colors` | `"natural"` (default) uses the animal's own colors, whatever `color` is. `"tinted"` makes them from `color`: the markings stay dark, and a giraffe's lines light. |
+| `halo.when` | A soft glow behind the label in the fur's base color, so it reads where the fur alone doesn't, as on a zebra's white and black at once. `"auto"` (default) adds it only when a pattern needs one; `"always"` or `"never"`. `halo.shade` moves its shade away from the label's, darker under a light label and lighter under a dark one (0.3 by default, in L from 0 to 1); `halo.size` spreads the glow and `halo.strength` sets how opaque it is (1 the usual for both). |
+
+## The fur
+
+| | |
+| --- | --- |
+| `fur.update(options)` | Changes some options. Groups merge value by value. |
+| `fur.set(options)` | Replaces all the options. |
+| `fur.play("hover" \| "leave" \| "click")` | Plays a motion as if the pointer did it. |
+| `fur.label` | `{ color, contrast, halo }`: the label color in use, its APCA Lc on the fur (over a pattern's markings too, or against the halo backing it), and whether a halo backs it, when `label` is set. |
+| `fur.reach` | How far, in CSS px, the longest hairs can reach past the element's box, to keep things clear of the fur. With an em `scale`, it changes with the font size. |
+| `fur.destroy()` | Removes the fur. |
+
+`supportsFur()`, also exported, says whether this browser can draw fur.
+
+## Notes
+
+- The fur is an enhancement. It needs WebGL2 on a real GPU; without it (or with only a slow software renderer), `hairy()` leaves the element exactly as it was, and `supportsFur()` returns false.
+- Every fur on a page shares one WebGL2 context, so there's no limit on how many you mount. Each draws into its own canvas behind its element.
+- Each fur is a cached frame until it's hovered, so only the hovered button animates.
+- It honors `prefers-reduced-motion`: the fur moves straight to where it rests, with no springs or poof.
+- Keyboard focus lifts the fur like hover, and Enter or Space plays the click.
+- The module touches no browser APIs until `hairy()` is called, so it can be imported during server rendering.