@craftedstudios/avatars 0.0.0-stage → 1.0.0

package/src/goo.js

@@ -0,0 +1,70 @@
+// The hover lean. A drop of the avatar's own material follows the pointer on a
+// spring and the shader melts it back into the body, so the avatar draws out
+// toward the pointer with a neck that thins as it goes. Every length is in
+// units of the radius r, so it feels the same at 16px and at 240px.
+//
+// Two numbers set it, both 0 to 1:
+//   stretch    how far the drop reaches: a slight bulge at 0, a drip hanging
+//              off the edge with a neck back to the body at 1
+//   thickness  how thick and slow it is: a thin neck that snaps back at 0, a
+//              heavy one that sinks back slowly at 1
+// The spring is critically damped at every setting, so it never overshoots.
+
+// The canvas reaches this far past the avatar's box on every side, in r. The
+// drop is never allowed further than fits inside it.
+export const PAD = 1;
+
+const mix = (a, b, t) => a + (b - a) * t;
+
+export function params(stretch = 1, thickness = 0.5) {
+  const s = Math.min(1, Math.max(0, stretch)), g = Math.min(1, Math.max(0, thickness));
+  const reach = mix(0.35, 1.6, s);
+  return {
+    reach,                    // the farthest the drop's center travels
+    range: reach + 0.8,       // the pull starts within this distance of the center
+    drop: mix(0.42, 0.58, g), // the drop's radius at rest
+    thin: 0.3 * s,            // how much smaller the drop gets at full reach
+    goo: mix(0.2, 0.7, g),    // how far apart body and drop still melt together
+    bulge: mix(0.06, 0.1, s), // how much of the pull the body itself follows
+    out: mix(220, 80, g),     // spring stiffness while reaching out
+    back: mix(70, 12, g),     // spring stiffness while sinking back
+  };
+}
+
+// Where the drop wants to be, relative to the center, for a pointer at
+// (dx, dy). It goes to the pointer, out to full reach, so past the edge it
+// hangs off the avatar under the cursor. Further out than that it lets go
+// smoothly by the end of the range.
+export function target(dx, dy, r, g) {
+  const dist = Math.hypot(dx, dy);
+  if (!(dist > 0) || dist > g.range * r) return [0, 0];
+  const reach = Math.min(g.reach, 1 + PAD - g.drop * (1 - g.thin) - 0.05) * r;
+  const edge = Math.min(1, (g.range * r - dist) / Math.max(1e-3, g.range * r - reach));
+  const ease = edge * edge * (3 - 2 * edge);
+  const m = Math.min(dist, reach) * (dist > reach ? ease : 1);
+  return [(dx / dist) * m, (dy / dist) * m];
+}
+
+// Advances one avatar's drop state { x, y, vx, vy } toward (tx, ty) by dt
+// seconds. Substepped so a dropped frame doesn't change how it moves.
+export function step(s, tx, ty, dt, g) {
+  const outward = tx * tx + ty * ty > s.x * s.x + s.y * s.y;
+  const k = outward ? g.out : g.back;
+  const c = 2 * Math.sqrt(k);
+  let left = Math.min(dt, 0.1);
+  while (left > 1e-6) {
+    const h = Math.min(left, 1 / 240);
+    s.vx += (k * (tx - s.x) - c * s.vx) * h;
+    s.vy += (k * (ty - s.y) - c * s.vy) * h;
+    s.x += s.vx * h;
+    s.y += s.vy * h;
+    left -= h;
+  }
+}
+
+export const settled = (s, tx, ty, r) =>
+  Math.abs(tx - s.x) + Math.abs(ty - s.y) < 0.002 * r && Math.abs(s.vx) + Math.abs(s.vy) < 0.02 * r;
+
+// The drop's radius for how far out it is.
+export const dropRadius = (s, r, g) =>
+  r * g.drop * (1 - g.thin * Math.min(1, Math.hypot(s.x, s.y) / (g.reach * r)));

package/src/index.js

@@ -0,0 +1,7 @@
+export { avatar } from './avatar.js';
+export { cursor } from './cursor.js';
+export { defineAvatarElement } from './element.js';
+export { toDataURL, toBlob } from './still.js';
+export { traits, EFFECTS, AUTO_EFFECTS } from './seed.js';
+export { nameFor } from './names.js';
+export { EFFECT_COLORS } from './color.js';

package/src/names.js

@@ -0,0 +1,44 @@
+// Anonymous names for cursors, from the seed: a friendly adjective and an
+// animal, like "Swift Otter". The same seed always gets the same name. The
+// words say nothing about color: at cursor size an avatar shows whichever of
+// its colors its layout puts in view, so a color name would often be wrong.
+// Like the rest of the seed mapping, these lists are frozen once 1.0 ships:
+// changing them renames everyone.
+
+import { fnv1a32 } from './seed.js';
+import { scramble } from './color.js';
+
+// Only words that are kind to whoever ends up with them.
+const ADJECTIVES = [
+  'Swift', 'Quiet', 'Bright', 'Gentle', 'Brave', 'Calm', 'Clever', 'Curious',
+  'Eager', 'Happy', 'Jolly', 'Lucky', 'Merry', 'Nimble', 'Plucky', 'Proud',
+  'Sunny', 'Witty', 'Cozy', 'Daring', 'Dapper', 'Breezy', 'Chipper', 'Snappy',
+  'Spry', 'Steady', 'Bold', 'Keen', 'Kind', 'Lively', 'Mellow', 'Noble',
+  'Patient', 'Peppy', 'Quick', 'Radiant', 'Serene', 'Sharp', 'Smooth', 'Sparkly',
+  'Stellar', 'Sturdy', 'Tidy', 'Upbeat', 'Vivid', 'Wise', 'Zippy', 'Cheery',
+];
+
+const ANIMALS = [
+  'Otter', 'Heron', 'Fox', 'Lynx', 'Owl', 'Hare', 'Finch', 'Wren',
+  'Swan', 'Crane', 'Falcon', 'Robin', 'Sparrow', 'Magpie', 'Puffin', 'Pelican',
+  'Koala', 'Panda', 'Badger', 'Beaver', 'Bison', 'Moose', 'Gazelle', 'Ibex',
+  'Llama', 'Alpaca', 'Zebra', 'Giraffe', 'Tapir', 'Lemur', 'Gecko', 'Turtle',
+  'Newt', 'Salmon', 'Marlin', 'Dolphin', 'Orca', 'Seal', 'Walrus', 'Narwhal',
+  'Manatee', 'Octopus', 'Crab', 'Jellyfish', 'Bee', 'Moth', 'Beetle', 'Cricket',
+  'Hedgehog', 'Squirrel', 'Ferret', 'Wolf', 'Tiger', 'Leopard', 'Jaguar', 'Ocelot',
+  'Bear', 'Kiwi', 'Toucan', 'Parrot', 'Kestrel', 'Osprey', 'Penguin', 'Quail',
+];
+
+/** The anonymous name a seed gets, like "Swift Otter". */
+export function nameFor(seed) {
+  const pick = scramble(fnv1a32(String(seed ?? '')) ^ 0x85ebca6b);
+  return `${ADJECTIVES[pick % ADJECTIVES.length]} ${ANIMALS[(pick >>> 8) % ANIMALS.length]}`;
+}
+
+// What a cursor's tag says: the app's name for the person, or the seed's
+// anonymous name when there isn't one, or nothing at all for `false`.
+export function tagName(name, seed) {
+  if (name === false) return null;
+  const given = typeof name === 'string' ? name.trim() : name == null ? '' : String(name);
+  return given || nameFor(seed);
+}

package/src/options.js

@@ -0,0 +1,88 @@
+import { traits } from './seed.js';
+import { css, effectColors, parseColor } from './color.js';
+
+const GRADIENTS = new Set(['linear', 'plasma', 'radial', 'thermal']);
+
+export const DEFAULTS = {
+  seed: '',
+  size: 32,
+  effect: 'auto',
+  colors: undefined,
+  motion: 'auto',
+  interaction: 'goo',
+  grain: 0.07,
+  speed: 1,
+  distortion: 0.5,
+  scale: 1,
+  stretch: 1,
+  thickness: 0.5,
+  shape: 'circle',
+  ring: 0,
+  ringColor: '#fff',
+  label: undefined,
+};
+
+const SHAPES = ['circle', 'squircle', 'square'];
+// Goo stretches the avatar's outline toward the pointer, which still shows at
+// 24px. The rest are Scenery's interactions, which move the pattern inside the
+// outline and leave the shape still.
+export const INTERACTIONS = ['goo', 'follow', 'repel', 'distort', 'pulse', 'orbit', 'turbulence', 'none'];
+const RADIUS = { circle: '50%', squircle: '30%', square: '0' };
+
+const num = (v, fallback, lo, hi) => {
+  const n = typeof v === 'string' && v.trim() !== '' ? Number(v) : v;
+  return typeof n === 'number' && Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : fallback;
+};
+
+// Fills in defaults and clamps what came in, so the rest of the code can trust
+// it. Accepts strings as well, because web component attributes are strings.
+export function resolve(input = {}) {
+  const o = { ...DEFAULTS };
+  for (const k in input) if (input[k] !== undefined && k in DEFAULTS) o[k] = input[k];
+  o.seed = String(o.seed ?? '');
+  o.size = num(o.size, 32, 1, 2048);
+  o.grain = num(o.grain, 0.07, 0, 1);
+  o.speed = num(o.speed, 1, 0, 4);
+  o.distortion = num(o.distortion, 0.5, 0, 1);
+  o.scale = num(o.scale, 1, 0.25, 4);
+  o.stretch = num(o.stretch, 1, 0, 1);
+  o.thickness = num(o.thickness, 0.5, 0, 1);
+  o.ring = num(o.ring, 0, 0, 64);
+  // A list, or a comma-separated string from a web component attribute.
+  o.colors = typeof o.colors === 'string' ? o.colors.split(',').map((c) => c.trim()).filter(Boolean) : Array.isArray(o.colors) ? o.colors.slice(0, 4) : undefined;
+  if (o.colors && !o.colors.length) o.colors = undefined;
+  o.shape = SHAPES.includes(o.shape) ? o.shape : 'circle';
+  o.motion = o.motion === 'still' ? 'still' : 'auto';
+  o.interaction = INTERACTIONS.includes(o.interaction) ? o.interaction : 'goo';
+  o.label = o.label ? String(o.label) : undefined;
+  o.traits = traits(o.seed, o);
+  o.palette = effectColors(o.traits.effect, o.traits.hue, o.colors, o.traits.tone);
+  // Small, four seeded colors average into one muddy blob, so a gradient
+  // keeps its first two: the same avatar with its accents dropped.
+  if (o.size < 40 && GRADIENTS.has(o.traits.effect) && !(o.colors || []).some((c) => parseColor(c))) {
+    const [a, b] = o.palette;
+    o.palette = [a, b, b, b];
+  }
+  return o;
+}
+
+// The host element's inline style. The server and the client both produce it
+// from the same options, which is what keeps hydration quiet: before WebGL
+// takes over, this gradient is the avatar.
+export function hostStyle(o) {
+  return {
+    display: 'inline-block',
+    position: 'relative',
+    flex: 'none',
+    verticalAlign: 'middle',
+    width: `${o.size}px`,
+    height: `${o.size}px`,
+    borderRadius: RADIUS[o.shape],
+    background: css(o.traits.effect, o.palette),
+    boxShadow: o.ring > 0 ? `inset 0 0 0 ${o.ring}px ${o.ringColor}` : 'none',
+  };
+}
+
+export function hostAttrs(o) {
+  return o.label ? { role: 'img', 'aria-label': o.label } : { 'aria-hidden': 'true' };
+}

package/src/react.js

@@ -0,0 +1,133 @@
+'use client';
+// React components. They render the host on the server with the fallback
+// gradient in place, so there is no empty circle or layout shift before the
+// client loads, and the live canvas joins it after hydration.
+
+import { createElement as h, useEffect, useId, useLayoutEffect, useRef } from 'react';
+import { resolve, hostStyle, hostAttrs, DEFAULTS } from './options.js';
+import { mount } from './avatar.js';
+import { ARROW, cursorColors, placeStyle, sizes as cursorSizes, styles as cursorStyles } from './cursor.js';
+import { tagName } from './names.js';
+
+const useLayout = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+const KEYS = Object.keys(DEFAULTS);
+
+function split(props) {
+  const opts = {}, rest = {};
+  for (const k in props) (KEYS.includes(k) ? opts : rest)[k] = props[k];
+  return [opts, rest];
+}
+
+function Live({ enter = false, className, style, ...props }) {
+  const [opts, rest] = split(props);
+  const o = resolve(opts);
+  const ref = useRef(null);
+  const live = useRef(null);
+  const latest = useRef(opts);
+  latest.current = opts;
+  const key = KEYS.map((k) => String(opts[k])).join('\u0000');
+
+  useLayout(() => { live.current?.update({ ...DEFAULTS, ...latest.current }); }, [key]);
+  useEffect(() => {
+    live.current = mount(ref.current, latest.current, { styled: true, enter });
+    return () => { live.current.destroy(); live.current = null; };
+  }, []);
+
+  return h('span', {
+    ...rest,
+    ref,
+    className: className ? `crafted-avatar ${className}` : 'crafted-avatar',
+    style: { ...hostStyle(o), ...style },
+    ...hostAttrs(o),
+  });
+}
+
+// <Avatar seed={user.id} size={32} />
+export function Avatar(props) {
+  return h(Live, props);
+}
+
+// "Who's here": overlapping avatars with a +N for the rest.
+//   <AvatarStack seeds={ids} size={24} max={4} />
+// A seed can also be an object with its own options, e.g.
+//   { seed: id, label: 'Ada', effect: 'radial' }
+export function AvatarStack({ seeds = [], size = 24, max = 4, ring = 1.5, ringColor = '#fff', overlap = 0.25, className, style, label, ...shared }) {
+  const items = seeds.map((s) => (s !== null && typeof s === 'object' ? s : { seed: s }));
+  const shown = items.slice(0, Math.max(0, max));
+  const more = items.length - shown.length;
+  // Avatars that arrive after the stack first mounts grow in; the ones that
+  // were there at load don't, so a page doesn't open with everything popping.
+  const seen = useRef(null);
+  useEffect(() => {
+    seen.current ||= new Set();
+    for (const it of shown) seen.current.add(String(it.seed));
+  });
+  const shapeRadius = { squircle: '30%', square: '0' }[shared.shape] || '50%';
+
+  const faces = shown.map((it, i) => h(Live, {
+    key: String(it.seed),
+    ...shared,
+    ring,
+    ringColor,
+    size,
+    ...it,
+    enter: !!seen.current && !seen.current.has(String(it.seed)),
+    style: { marginLeft: i ? -size * overlap : 0, zIndex: shown.length - i, ...it.style },
+  }));
+  if (more > 0) {
+    faces.push(h('span', {
+      key: '+more',
+      className: 'crafted-avatar-more',
+      style: {
+        display: 'inline-flex', alignItems: 'center', justifyContent: 'center', flex: 'none',
+        position: 'relative', boxSizing: 'border-box', width: size, height: size,
+        marginLeft: shown.length ? -size * overlap : 0, borderRadius: shapeRadius,
+        background: '#F1F2F3', color: '#070B0E', boxShadow: `inset 0 0 0 ${ring}px ${ringColor}`,
+        fontSize: Math.max(9, Math.round(size * 0.4)), lineHeight: 1, fontVariantNumeric: 'tabular-nums',
+        letterSpacing: '-0.02em',
+      },
+      'aria-hidden': 'true',
+    }, `+${more}`));
+  }
+  return h('div', {
+    className: className ? `crafted-avatar-stack ${className}` : 'crafted-avatar-stack',
+    role: 'group',
+    'aria-label': label ?? `${items.length} ${items.length === 1 ? 'person' : 'people'}`,
+    style: { display: 'inline-flex', alignItems: 'center', isolation: 'isolate', ...style },
+  }, faces);
+}
+
+// A presence cursor with the avatar built in. The app says where it is; the
+// tip lands on x, y inside the nearest positioned ancestor.
+//   <Cursor seed={user.id} name={user.name} variant="avatar" x={x} y={y} />
+// Without x and y it sits in the flow, which suits a preview or a legend.
+export function Cursor({ variant = 'arrow', name, x, y, zoom = 1, className, style, ...options }) {
+  const gradient = `crafted-cursor-${useId().replace(/:/g, '')}`;
+  const colors = cursorColors(options);
+  const look = { ...options, interaction: 'none' };
+  const placed = typeof x === 'number' && typeof y === 'number';
+  const size = cursorSizes(zoom);
+  const box = variant === 'avatar' ? size.drop : size.arrow;
+  const root = placed
+    ? { ...cursorStyles.root, transform: placeStyle(variant, x, y, zoom) }
+    : { position: 'relative', display: 'inline-block', verticalAlign: 'top', width: box, height: box, pointerEvents: 'none' };
+
+  const pointer = variant === 'avatar'
+    ? h('span', { style: cursorStyles.drop(zoom) }, h(Live, { ...look, size: size.drop, shape: 'square' }))
+    : h('svg', { viewBox: '0 0 24 24', width: size.arrow, height: size.arrow, style: cursorStyles.arrow(zoom), 'aria-hidden': 'true' },
+      h('defs', null, h('linearGradient', { id: gradient, x1: 0.1, y1: 0.1, x2: 0.9, y2: 0.9 },
+        h('stop', { offset: 0, stopColor: colors[0] }),
+        h('stop', { offset: 1, stopColor: colors[1] }))),
+      h('path', { d: ARROW, fill: `url(#${gradient})`, stroke: '#fff', strokeWidth: 1.6, strokeLinejoin: 'round' }));
+
+  const label = tagName(name, options.seed);
+  const tag = label ? h('span', { style: cursorStyles.tag(variant, zoom) },
+    variant === 'avatar' ? null : h(Live, { ...look, size: size.dot }),
+    label) : null;
+
+  return h('span', {
+    className: className ? `crafted-cursor ${className}` : 'crafted-cursor',
+    'aria-hidden': 'true',
+    style: { ...root, ...style },
+  }, pointer, tag);
+}