@kolkrabbi/kol-component 0.121.0 → 0.122.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.121.0",
+  "version": "0.122.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
     "./utilities/markdownToHtml": "./src/utilities/markdownToHtml.js",
     "./utilities/mediaKinds": "./src/utilities/mediaKinds.js",
     "./utilities/ratios": "./src/utilities/ratios.js",
+    "./utilities/motion": "./src/utilities/motion.js",
     "./hooks/*": "./src/hooks/*.js"
   },
   "dependencies": {

package/src/atoms/ActionButton.jsx

@@ -1,4 +1,5 @@
 import { useRef, useState, useEffect, useLayoutEffect } from 'react'
+import { DURATION } from '../utilities/motion.js'
 import gsap from 'gsap'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { glyphSize } from '../hooks/glyphLadders.js'
@@ -73,7 +74,7 @@ const HOUSE_EASE = [0.4, 0, 0.2, 1]
  * not a mode. The release then plays the full bounce out. */
 const PRESS_HOLD = 1600
 
-const SWAP_MS = 500
+const SWAP_MS = DURATION.spring  /* the house 500 (utilities/motion.js) */
 
 const CHROME = {
   copy: 'kol-copy-btn',

package/src/atoms/ViewToggle.jsx

@@ -73,8 +73,12 @@ const ViewToggle = ({
     )
   }
 
+  /* THE WELL IS INSET (ViewToggleWellGap, kol-website 2026-08-28): `p-1` put the box 4px past the
+   * last chip on every side, so a row's `gap-4` read 20 on this side and 16 on the other, and every
+   * consumer subtracted it with a `-ml-1` on the neighbour. `-mx-1` draws the padding inward from the
+   * declared box — the chips sit where the box says, the well bleeds 4px into the gap. */
   const containerClasses = isIconVariant
-    ? `kol-view-toggle inline-flex items-center gap-1 p-1 bg-surface-secondary rounded ${toneClass(tone)} ${className}`.replace(/\s+/g, ' ').trim()
+    ? `kol-view-toggle inline-flex items-center gap-1 p-1 -mx-1 bg-surface-secondary rounded ${toneClass(tone)} ${className}`.replace(/\s+/g, ' ').trim()
     : `flex gap-2 ${className}`
 
   const buttonClasses = (isActive) => {

package/src/hooks/useTilt.js

@@ -1,5 +1,6 @@
 import { useRef } from 'react'
 import { useMotionValue, useSpring, useTransform } from 'framer-motion'
+import { SPRING } from '../utilities/motion.js'
 
 /**
  * Pointer-driven 3D tilt (framer-motion springs) — the ONE tilt hook.
@@ -12,7 +13,9 @@ import { useMotionValue, useSpring, useTransform } from 'framer-motion'
  * (e.g. TiltCard's `grounded` zone-snapping).
  *
  * Defaults are the design: tilt ±4°, spring 350/35, perspective 700,
- * rest position center (0.5/0.5).
+ * rest position center (0.5/0.5). The two spring sets are `SPRING.tilt` and
+ * `SPRING.lazy` in `utilities/motion.js` — the JS mirror of kol-animation.css,
+ * so a tween elsewhere in the estate cannot drift from this feel (2026-08-28).
  *
  * `grounded` (ShelfCardTiltWrapsCard, kol-website 2026-08-27 — lifted out of
  * TiltCardInner so the shelf and the card share ONE feel, no new component):
@@ -23,8 +26,8 @@ import { useMotionValue, useSpring, useTransform } from 'framer-motion'
 export default function useTilt({
   magnitude = 4,
   perspective = 700,
-  stiffness = 350,
-  damping = 35,
+  stiffness = SPRING.tilt.stiffness,
+  damping = SPRING.tilt.damping,
   grounded = false,
 } = {}) {
   const ref = useRef(null)
@@ -38,7 +41,7 @@ export default function useTilt({
    * SELECTED when asked for — a free tilt pays two idle springs, nothing more */
   const zones = 3
   const snap = (v) => Math.round(v * zones) / zones
-  const lazy = { stiffness: 250, damping: 25, mass: 0.6 }
+  const lazy = SPRING.lazy
   const lazyX = useSpring(useTransform(springX, (v) => Math.min(0, snap(-v / magnitude) * 2.5)), lazy)
   const lazyY = useSpring(useTransform(springY, (v) => snap(v / magnitude) * 2.5), lazy)
   const rotateX = grounded ? lazyX : springX

package/src/utilities/motion.js

@@ -0,0 +1,65 @@
+/**
+ * motion.js — the JS side of the motion sheet (user ruling 2026-08-28:
+ * "localise animation to its own css … and use it to localise all the gsap
+ * framer shit we are doing").
+ *
+ * kol-theme's `kol-animation.css` is where the estate's CSS motion lives. This
+ * is its mirror for the motion CSS cannot express — a gsap tween, a framer
+ * spring — so a hand-typed `duration: 0.5, ease: "power3.out"` in some
+ * component is not a second, private vocabulary. Same numbers, one import.
+ *
+ * NOT here: a domain's own physics — the foundry's pressure damping, the
+ * marquee's px/s, a scroll-scrub timeline. Those are content, not chrome, and
+ * flattening them into house constants would say they are interchangeable.
+ */
+
+/* The house curves. `HOUSE` is `--kol-ease-house` as framer takes it (a
+ * cubic-bezier array); the gsap column is the nearest named equivalent, so a
+ * tween and a transition on the same element do not disagree. */
+export const EASE = {
+  house: [0.4, 0, 0.2, 1],
+  houseGsap: 'power2.inOut',
+  bounce: [0.34, 1.56, 0.64, 1],
+  /* symmetric in-out — an ease-out pops the first 20 % and crawls the rest,
+   * which reads as a jerk on a long fade (user, on the rail pill 2026-08-28) */
+  longFade: [0.45, 0, 0.55, 1],
+  outGsap: 'power3.out',
+}
+
+/* Milliseconds, mirroring `--kol-transition-*` in kol-design-tokens.css.
+ * `s()` because gsap counts in seconds and framer in seconds — the CSS side is
+ * the source, so the conversion lives here rather than at each call site. */
+export const DURATION = { fast: 150, base: 200, slow: 300, spring: 500, zoom: 600 }
+export const s = (ms) => ms / 1000
+
+/* framer springs. `tilt` is the Tilt family's feel; `lazy` is the grounded
+ * chase (heavier, slower to settle) — the two the hook already had inline. */
+export const SPRING = {
+  tilt: { stiffness: 350, damping: 35 },
+  lazy: { stiffness: 250, damping: 25, mass: 0.6 },
+}
+
+/* THE RAIL'S GRAB EDGE (RailFlatGrabOpen, kol-mirror 2026-08-28 — kol-r2b2's
+ * pill). The chrome is `.kol-rail-grab` in kol-animation.css; these are the
+ * numbers JS owns, because they are pointer behaviour, not paint:
+ *
+ *   near / sleep  the pill wakes within 20px of the line and sleeps only past
+ *                 40 — hovering the line itself flapped the class every frame
+ *                 and restarted the fade, so the hysteresis is not optional
+ *   marks         it rests on 20/40/60/80 % of the rail's height and is STICKY:
+ *                 it leaves a mark only within `stick` of the pitch to another
+ *                 (user: "following the mouse a little too much"). The middle
+ *                 of each gap is dead on purpose
+ *   travel        a long chase, so the pill trails the pointer and catches up
+ *   snap          the width tween on release
+ *   slop          under this, a pointerdown/up is a CLICK, not a drag
+ */
+export const GRAB = {
+  near: 20,
+  sleep: 40,
+  marks: [0.2, 0.4, 0.6, 0.8],
+  stick: 0.2 * 0.3,
+  travel: { duration: 2.8, ease: EASE.outGsap },
+  snap: { duration: 0.5, ease: EASE.outGsap },
+  slop: 3,
+}