@kolkrabbi/kol-component 0.121.1 → 0.123.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.121.1",
+  "version": "0.123.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/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/molecules/Dropdown.jsx

@@ -148,6 +148,13 @@ const Dropdown = ({
             return (
               <MenuDropdownItem
                 key={option.value}
+                /* NO HOVER STATE ANYWHERE ON A DROPDOWN (user 2026-08-28,
+                 * "delete any hover state on dropdowns"): the trigger was
+                 * already pinned in all three variants — primary and outline
+                 * back to rest in kol-theme, grey carrying no hover rule at
+                 * all — and this was the last one left, the option row's ink
+                 * brighten. The check mark is what marks the current value. */
+                hover={false}
                 onClick={() => handleSelect(option)}
                 shortcut={isActive ? <Icon name="check" size={11} /> : undefined}
               >

package/src/molecules/MenuItem.jsx

@@ -78,6 +78,11 @@ export function MenuItem({
 
 /**
  * MenuDropdownItem — action row inside a MenuItem's dropdown panel.
+ *
+ * `hover` (default true) — `false` drops the ink brighten, for a panel ruled
+ * to carry NO hover state at all (user 2026-08-28, on `Dropdown`: "delete any
+ * hover state on dropdowns"). Scoped to the caller: a MenuItem's own menu keeps
+ * its hover, because that ruling was about the select, not every panel.
  * Renders as a button so it picks up disabled, focus, and keyboard
  * activation. The parent MenuItem closes automatically on click via a
  * delegated handler that matches the `data-menu-item` attr.
@@ -89,7 +94,7 @@ export function MenuItem({
  *   - children  — main label, flex-1.
  *   - shortcut  — trailing content (text shortcut hint, ✓ marker, or icon).
  */
-export function MenuDropdownItem({ onClick, disabled, prefix, iconLeft, shortcut, children }) {
+export function MenuDropdownItem({ onClick, disabled, prefix, iconLeft, shortcut, hover = true, children }) {
   return (
     <button
       type="button"
@@ -97,7 +102,7 @@ export function MenuDropdownItem({ onClick, disabled, prefix, iconLeft, shortcut
       onClick={onClick}
       disabled={disabled}
       role="menuitem"
-      className="w-full kol-helper-12 px-3 h-8 shrink-0 inline-flex items-center gap-2 text-body hover:text-emphasis disabled:opacity-40 disabled:cursor-not-allowed text-left"
+      className={`w-full kol-helper-12 px-3 h-8 shrink-0 inline-flex items-center gap-2 text-body ${hover ? 'hover:text-emphasis' : ''} disabled:opacity-40 disabled:cursor-not-allowed text-left`}
     >
       {prefix && <span className="shrink-0 inline-flex items-center">{prefix}</span>}
       {iconLeft && <span className="shrink-0 w-4 inline-flex items-center justify-center">{iconLeft}</span>}

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,
+}