kang-components 0.0.1 → 0.1.0

package/README.md

@@ -1,50 +1,81 @@
-# React + TypeScript + Vite
+# kang-components
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Generic, domain-free React UI primitives. Built to be consumed by Xunzi (and
+anything else) while it migrates off `ymy-components` — see the
+[Xunzi straddle epic](https://github.com/LoganConnor44/xunzi/issues/294).
 
-Currently, two official plugins are available:
+## Design constraints
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- **No app domain knowledge.** No HSK, challenge, friend, route, or Redux
+  concepts. Primitives only.
+- **CSS-first.** Simple interaction primitives return plain CSS strings — no
+  CSS-in-JS runtime dependency. Use JS animation only when it earns the cost.
+- **Additive, non-breaking APIs** before each manual npm publication.
 
-## Expanding the ESLint configuration
+## Install
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+```bash
+npm install kang-components
+```
+
+`react` is an optional peer dependency — only required if you use a hook
+(e.g. `useAnimatedAction`). The press primitives are pure strings and need
+nothing.
+
+## Press primitives
+
+CSS-first press feedback. Each helper returns a plain CSS string you interpolate
+into your styling layer (styled-components shown):
+
+```ts
+import styled from 'styled-components';
+import { pressPrimary, pressSubtle } from 'kang-components';
+
+// Action buttons (scale 0.95)
+const Button = styled.button`
+	${pressPrimary()}
+`;
+
+// Large tappable surfaces (scale 0.97)
+const Tile = styled.button`
+	${pressSubtle()}
+`;
+```
+
+When the element also transitions other properties, pass them via
+`extraTransition` so they share the one `transition` declaration:
 
-- Configure the top-level `parserOptions` property like this:
+```ts
+const Row = styled.button`
+	${pressSubtle('background-color 0.15s ease-out')}
+`;
+```
+
+For elements whose `transform` is driven elsewhere (e.g. a JS spring), use the
+`*Scale` variants, which animate the CSS `scale` property instead:
 
-```js
-export default tseslint.config({
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
+```ts
+import { pressPrimaryScale, pressSubtleScale } from 'kang-components';
 ```
 
-- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
-- Optionally add `...tseslint.configs.stylisticTypeChecked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
-
-```js
-// eslint.config.js
-import react from 'eslint-plugin-react'
-
-export default tseslint.config({
-  // Set the react version
-  settings: { react: { version: '18.3' } },
-  plugins: {
-    // Add the react plugin
-    react,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended rules
-    ...react.configs.recommended.rules,
-    ...react.configs['jsx-runtime'].rules,
-  },
-})
+Exports: `pressPrimary`, `pressSubtle`, `pressPrimaryScale`, `pressSubtleScale`,
+plus the constants `BOUNCE_CURVE`, `PRESS_SCALE_PRIMARY`, `PRESS_SCALE_SUBTLE`.
+
+## `useAnimatedAction`
+
+Delays an action callback so visual feedback (ripple, press animation) is
+perceived before the UI transitions away. Defaults to 180ms; clears pending
+timeouts on unmount.
+
+```ts
+import { useAnimatedAction } from 'kang-components';
+
+const act = useAnimatedAction();
+const onClick = () => act(() => navigate('/next'));
+```
+
+## Build
+
+```bash
+npm run build   # tsc → dist (ESM + .d.ts)
 ```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { BOUNCE_CURVE, PRESS_SCALE_PRIMARY, PRESS_SCALE_SUBTLE, pressPrimary, pressSubtle, pressPrimaryScale, pressSubtleScale, } from './press.js';
+export { useAnimatedAction } from './use-animated-action.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { BOUNCE_CURVE, PRESS_SCALE_PRIMARY, PRESS_SCALE_SUBTLE, pressPrimary, pressSubtle, pressPrimaryScale, pressSubtleScale, } from './press.js';
+export { useAnimatedAction } from './use-animated-action.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/press.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Press-feedback CSS primitives — the generic press language for Kang consumers.
+ *
+ * CSS-first: every helper returns a plain CSS string (no styled-components or
+ * other CSS-in-JS dependency). Interpolate the result into whatever template
+ * your styling layer uses, e.g. styled-components:
+ *
+ *   const Button = styled.button`
+ *     ${pressPrimary()}
+ *   `;
+ *
+ * Two tiers:
+ * - pressPrimary (scale 0.95): discrete action buttons — CTAs, icon buttons,
+ *   confirm/cancel buttons, nav controls.
+ * - pressSubtle (scale 0.97): large tappable surfaces — tiles, cards, list
+ *   rows, picker options, tabs.
+ *
+ * Physics: press down fast (60ms, ease-out); release with a bouncy spring-back
+ * (300ms, cubic-bezier overshooting ~6%) — a rubber-band feel without JS spring
+ * physics.
+ *
+ * Each helper owns the `transition` declaration in both rest and pressed
+ * states. If the element transitions other properties (background, color,
+ * opacity...), pass them via `extraTransition` instead of declaring a second
+ * `transition` — a separate declaration would override this one.
+ *
+ * The *Scale variants animate the CSS `scale` property instead of `transform`,
+ * for elements whose `transform` is already controlled elsewhere (e.g. a JS
+ * spring).
+ */
+export declare const BOUNCE_CURVE = "cubic-bezier(0.34, 1.56, 0.64, 1)";
+export declare const PRESS_SCALE_PRIMARY = 0.95;
+export declare const PRESS_SCALE_SUBTLE = 0.97;
+/** Action buttons: CTAs, icon buttons, confirm/cancel. */
+export declare const pressPrimary: (extraTransition?: string) => string;
+/** Tappable surfaces: tiles, cards, rows, tabs. */
+export declare const pressSubtle: (extraTransition?: string) => string;
+/** pressPrimary for elements whose `transform` is controlled elsewhere (uses CSS `scale`). */
+export declare const pressPrimaryScale: (extraTransition?: string) => string;
+/** pressSubtle for elements whose `transform` is controlled elsewhere (uses CSS `scale`). */
+export declare const pressSubtleScale: (extraTransition?: string) => string;
+//# sourceMappingURL=press.d.ts.map

package/dist/press.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"press.d.ts","sourceRoot":"","sources":["../src/press.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAO,MAAM,YAAY,sCAAsC,CAAC;AAEhE,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAwBvC,0DAA0D;AAC1D,eAAO,MAAM,YAAY,qBAAsB,MAAM,KAAG,MACN,CAAC;AAEnD,mDAAmD;AACnD,eAAO,MAAM,WAAW,qBAAsB,MAAM,KAAG,MACN,CAAC;AAElD,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,qBAAsB,MAAM,KAAG,MACN,CAAC;AAExD,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,qBAAsB,MAAM,KAAG,MACN,CAAC"}

package/dist/press.js

@@ -0,0 +1,60 @@
+/**
+ * Press-feedback CSS primitives — the generic press language for Kang consumers.
+ *
+ * CSS-first: every helper returns a plain CSS string (no styled-components or
+ * other CSS-in-JS dependency). Interpolate the result into whatever template
+ * your styling layer uses, e.g. styled-components:
+ *
+ *   const Button = styled.button`
+ *     ${pressPrimary()}
+ *   `;
+ *
+ * Two tiers:
+ * - pressPrimary (scale 0.95): discrete action buttons — CTAs, icon buttons,
+ *   confirm/cancel buttons, nav controls.
+ * - pressSubtle (scale 0.97): large tappable surfaces — tiles, cards, list
+ *   rows, picker options, tabs.
+ *
+ * Physics: press down fast (60ms, ease-out); release with a bouncy spring-back
+ * (300ms, cubic-bezier overshooting ~6%) — a rubber-band feel without JS spring
+ * physics.
+ *
+ * Each helper owns the `transition` declaration in both rest and pressed
+ * states. If the element transitions other properties (background, color,
+ * opacity...), pass them via `extraTransition` instead of declaring a second
+ * `transition` — a separate declaration would override this one.
+ *
+ * The *Scale variants animate the CSS `scale` property instead of `transform`,
+ * for elements whose `transform` is already controlled elsewhere (e.g. a JS
+ * spring).
+ */
+export const BOUNCE_CURVE = 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+export const PRESS_SCALE_PRIMARY = 0.95;
+export const PRESS_SCALE_SUBTLE = 0.97;
+const transitionFor = (property, duration, easing, extra) => `transition: ${property} ${duration} ${easing}${extra ? `, ${extra}` : ''};`;
+const springPress = (scaleValue, extraTransition) => `
+	${transitionFor('transform', '0.3s', BOUNCE_CURVE, extraTransition)}
+	will-change: transform;
+
+	&:active {
+		transform: scale(${scaleValue});
+		${transitionFor('transform', '0.06s', 'ease-out', extraTransition)}
+	}
+`;
+const springPressScale = (scaleValue, extraTransition) => `
+	${transitionFor('scale', '0.3s', BOUNCE_CURVE, extraTransition)}
+
+	&:active {
+		scale: ${scaleValue};
+		${transitionFor('scale', '0.06s', 'ease-out', extraTransition)}
+	}
+`;
+/** Action buttons: CTAs, icon buttons, confirm/cancel. */
+export const pressPrimary = (extraTransition) => springPress(PRESS_SCALE_PRIMARY, extraTransition);
+/** Tappable surfaces: tiles, cards, rows, tabs. */
+export const pressSubtle = (extraTransition) => springPress(PRESS_SCALE_SUBTLE, extraTransition);
+/** pressPrimary for elements whose `transform` is controlled elsewhere (uses CSS `scale`). */
+export const pressPrimaryScale = (extraTransition) => springPressScale(PRESS_SCALE_PRIMARY, extraTransition);
+/** pressSubtle for elements whose `transform` is controlled elsewhere (uses CSS `scale`). */
+export const pressSubtleScale = (extraTransition) => springPressScale(PRESS_SCALE_SUBTLE, extraTransition);
+//# sourceMappingURL=press.js.map

package/dist/press.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"press.js","sourceRoot":"","sources":["../src/press.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEhE,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAE,QAAgB,EAAE,MAAc,EAAE,KAAc,EAAU,EAAE,CACpG,eAAe,QAAQ,IAAI,QAAQ,IAAI,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;AAE9E,MAAM,WAAW,GAAG,CAAC,UAAkB,EAAE,eAAwB,EAAU,EAAE,CAAC;GAC3E,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,CAAC;;;;qBAI/C,UAAU;IAC3B,aAAa,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC;;CAEnE,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,UAAkB,EAAE,eAAwB,EAAU,EAAE,CAAC;GAChF,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,CAAC;;;WAGrD,UAAU;IACjB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC;;CAE/D,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,eAAwB,EAAU,EAAE,CAChE,WAAW,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;AAEnD,mDAAmD;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,eAAwB,EAAU,EAAE,CAC/D,WAAW,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;AAElD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,eAAwB,EAAU,EAAE,CACrE,gBAAgB,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;AAExD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,eAAwB,EAAU,EAAE,CACpE,gBAAgB,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC"}

package/dist/use-animated-action.d.ts

@@ -0,0 +1,2 @@
+export declare function useAnimatedAction(delayMs?: number): (callback: () => void) => void;
+//# sourceMappingURL=use-animated-action.d.ts.map

package/dist/use-animated-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-animated-action.d.ts","sourceRoot":"","sources":["../src/use-animated-action.ts"],"names":[],"mappings":"AAaA,wBAAgB,iBAAiB,CAAC,OAAO,SAAmB,cAY/C,MAAM,IAAI,UAWtB"}

package/dist/use-animated-action.js

@@ -0,0 +1,30 @@
+import { useCallback, useRef, useEffect } from 'react';
+/**
+ * Delays an action callback so that visual feedback (ripple, press animation)
+ * has time to be perceived before the UI transitions away.
+ *
+ * Uses 180ms by default — long enough to see the ripple start expanding,
+ * short enough to feel responsive (under the 200ms "instant" threshold).
+ *
+ * All pending timeouts are cleared on unmount.
+ */
+const DEFAULT_DELAY_MS = 180;
+export function useAnimatedAction(delayMs = DEFAULT_DELAY_MS) {
+    const timeoutsRef = useRef(new Set());
+    useEffect(() => {
+        return () => {
+            for (const id of timeoutsRef.current) {
+                clearTimeout(id);
+            }
+        };
+    }, []);
+    const act = useCallback((callback) => {
+        const id = setTimeout(() => {
+            timeoutsRef.current.delete(id);
+            callback();
+        }, delayMs);
+        timeoutsRef.current.add(id);
+    }, [delayMs]);
+    return act;
+}
+//# sourceMappingURL=use-animated-action.js.map

package/dist/use-animated-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-animated-action.js","sourceRoot":"","sources":["../src/use-animated-action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAG,gBAAgB;IAC3D,MAAM,WAAW,GAAG,MAAM,CAAqC,IAAI,GAAG,EAAE,CAAC,CAAC;IAE1E,SAAS,CAAC,GAAG,EAAE;QACd,OAAO,GAAG,EAAE;YACX,KAAK,MAAM,EAAE,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;gBACtC,YAAY,CAAC,EAAE,CAAC,CAAC;YAClB,CAAC;QACF,CAAC,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,GAAG,GAAG,WAAW,CACtB,CAAC,QAAoB,EAAE,EAAE;QACxB,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC/B,QAAQ,EAAE,CAAC;QACZ,CAAC,EAAE,OAAO,CAAC,CAAC;QACZ,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC,EACD,CAAC,OAAO,CAAC,CACT,CAAC;IAEF,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,43 +1,41 @@
 {
 	"name": "kang-components",
-	"version": "0.0.1",
+	"version": "0.1.0",
+	"description": "Generic, domain-free React UI primitives (CSS-first press feedback, delayed-action hook).",
 	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/LoganConnor44/kang-components.git"
+	},
 	"files": [
 		"dist"
 	],
-	"main": "./dist/kang-components.umd.cjs",
-	"module": "./dist/kang-components.js",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
-			"import": "./dist/kang-components.js",
-			"require": "./dist/kang-components.umd.cjs"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
 		}
 	},
+	"sideEffects": false,
 	"scripts": {
-		"dev": "vite",
-		"prebuild": "rm -rf dist",
-		"build": "tsc -b && vite build",
-		"lint": "eslint .",
-		"preview": "vite preview",
-    "prepublish": "npm run build",
-    "publish": "npm publish"
+		"build": "tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run build"
 	},
-	"dependencies": {
-		"react": "^18.3.1",
-		"react-dom": "^18.3.1"
+	"peerDependencies": {
+		"react": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.17.0",
-		"@types/node": "^22.10.5",
 		"@types/react": "^18.3.18",
-		"@types/react-dom": "^18.3.5",
-		"@vitejs/plugin-react-swc": "^3.5.0",
-		"eslint": "^9.17.0",
-		"eslint-plugin-react-hooks": "^5.0.0",
-		"eslint-plugin-react-refresh": "^0.4.16",
-		"globals": "^15.14.0",
-		"typescript": "~5.6.2",
-		"typescript-eslint": "^8.18.2",
-		"vite": "^6.0.5"
+		"react": "^18.3.1",
+		"typescript": "~5.6.2"
 	}
 }

package/dist/kang-components.js

@@ -1,5 +0,0 @@
-import { jsx as o } from "react/jsx-runtime";
-const e = ({ children: t }) => /* @__PURE__ */ o("button", { children: t });
-export {
-  e as Test
-};

package/dist/kang-components.umd.cjs

@@ -1 +0,0 @@
-(function(e,t){typeof exports=="object"&&typeof module<"u"?t(exports,require("react/jsx-runtime")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime"],t):(e=typeof globalThis<"u"?globalThis:e||self,t(e.KangComponents={},e["react/jsx-runtime"]))})(this,function(e,t){"use strict";const n=({children:i})=>t.jsx("button",{children:i});e.Test=n,Object.defineProperty(e,Symbol.toStringTag,{value:"Module"})});

package/dist/vite.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>