kang-components 0.1.0 → 0.3.0

package/README.md

@@ -74,6 +74,27 @@ const act = useAnimatedAction();
 const onClick = () => act(() => navigate('/next'));
 ```
 
+## Action-sheet primitives
+
+CSS-first layout for a bottom-sheet "actions" panel — a vertical container, a
+list, and tappable action rows with subtle press feedback. Colors stay with the
+consumer: `actionSheetRow` takes the pressed-state background, so Kang carries no
+theme knowledge.
+
+```ts
+import styled from 'styled-components';
+import { actionSheetContainer, actionSheetList, actionSheetRow } from 'kang-components';
+
+const Container = styled.div`${actionSheetContainer()}`;
+const List = styled.div`${actionSheetList()}`;
+const Row = styled.button`
+	${({ theme }) => actionSheetRow(theme.colors.surfaceVariant)}
+`;
+```
+
+Per-row content (leading icon, label, destructive tint, ripple) is the
+consumer's to layer on top of the row.
+
 ## Build
 
 ```bash

package/dist/action-sheet.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Action-sheet layout primitives — CSS-first, domain-free.
+ *
+ * The shared shape of a bottom-sheet "actions" panel: a vertical container, a
+ * list, and tappable action rows with subtle press feedback. Each helper
+ * returns a plain CSS string to interpolate into your styling layer.
+ *
+ *   const Container = styled.div`${actionSheetContainer()}`;
+ *   const List = styled.div`${actionSheetList()}`;
+ *   const Row = styled.button`${actionSheetRow(theme.colors.surfaceVariant)}`;
+ *
+ * Colors stay with the consumer: `actionSheetRow` takes the pressed-state
+ * background so Kang carries no theme knowledge. Per-row content styling (icon
+ * tint, destructive text, etc.) is the consumer's to layer on.
+ */
+/** Vertical action-sheet wrapper: column flex with standard sheet padding. */
+export declare const actionSheetContainer: () => string;
+/** The list of action rows. */
+export declare const actionSheetList: () => string;
+/**
+ * A single tappable action row: leading-icon + label layout with subtle press
+ * feedback (`pressSubtle`, with a background-color transition). Pass
+ * `activeBackground` to tint the pressed state; omit it to leave the pressed
+ * background to the consumer.
+ */
+export declare const actionSheetRow: (activeBackground?: string) => string;
+//# sourceMappingURL=action-sheet.d.ts.map

package/dist/action-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-sheet.d.ts","sourceRoot":"","sources":["../src/action-sheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,QAAO,MAKvC,CAAC;AAEF,+BAA+B;AAC/B,eAAO,MAAM,eAAe,QAAO,MAGlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,sBAAuB,MAAM,KAAG,MAiB1D,CAAC"}

package/dist/action-sheet.js

@@ -0,0 +1,53 @@
+/**
+ * Action-sheet layout primitives — CSS-first, domain-free.
+ *
+ * The shared shape of a bottom-sheet "actions" panel: a vertical container, a
+ * list, and tappable action rows with subtle press feedback. Each helper
+ * returns a plain CSS string to interpolate into your styling layer.
+ *
+ *   const Container = styled.div`${actionSheetContainer()}`;
+ *   const List = styled.div`${actionSheetList()}`;
+ *   const Row = styled.button`${actionSheetRow(theme.colors.surfaceVariant)}`;
+ *
+ * Colors stay with the consumer: `actionSheetRow` takes the pressed-state
+ * background so Kang carries no theme knowledge. Per-row content styling (icon
+ * tint, destructive text, etc.) is the consumer's to layer on.
+ */
+import { pressSubtle } from './press.js';
+/** Vertical action-sheet wrapper: column flex with standard sheet padding. */
+export const actionSheetContainer = () => `
+	display: flex;
+	flex-direction: column;
+	gap: 1rem;
+	padding: 0.5rem 0;
+`;
+/** The list of action rows. */
+export const actionSheetList = () => `
+	display: flex;
+	flex-direction: column;
+`;
+/**
+ * A single tappable action row: leading-icon + label layout with subtle press
+ * feedback (`pressSubtle`, with a background-color transition). Pass
+ * `activeBackground` to tint the pressed state; omit it to leave the pressed
+ * background to the consumer.
+ */
+export const actionSheetRow = (activeBackground) => `
+	position: relative;
+	display: flex;
+	align-items: center;
+	gap: 1rem;
+	padding: 1rem;
+	background: none;
+	border: none;
+	border-radius: 0.75rem;
+	cursor: pointer;
+	overflow: hidden;
+	${pressSubtle('background-color 0.15s ease-out')}
+	-webkit-tap-highlight-color: transparent;
+${activeBackground ? `
+	&:active {
+		background-color: ${activeBackground};
+	}` : ''}
+`;
+//# sourceMappingURL=action-sheet.js.map

package/dist/action-sheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-sheet.js","sourceRoot":"","sources":["../src/action-sheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAW,EAAE,CAAC;;;;;CAKjD,CAAC;AAEF,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG,GAAW,EAAE,CAAC;;;CAG5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,gBAAyB,EAAU,EAAE,CAAC;;;;;;;;;;;GAWlE,WAAW,CAAC,iCAAiC,CAAC;;EAE/C,gBAAgB,CAAC,CAAC,CAAC;;sBAEC,gBAAgB;GACnC,CAAC,CAAC,CAAC,EAAE;CACP,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { BOUNCE_CURVE, PRESS_SCALE_PRIMARY, PRESS_SCALE_SUBTLE, pressPrimary, pressSubtle, pressPrimaryScale, pressSubtleScale, } from './press.js';
 export { useAnimatedAction } from './use-animated-action.js';
+export { actionSheetContainer, actionSheetList, actionSheetRow, } from './action-sheet.js';
+export { Ripple, rippleAnimation, useRipple } from './ripple.js';
+export type { RippleState } from './ripple.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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;AAE7D,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,cAAc,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export { BOUNCE_CURVE, PRESS_SCALE_PRIMARY, PRESS_SCALE_SUBTLE, pressPrimary, pressSubtle, pressPrimaryScale, pressSubtleScale, } from './press.js';
 export { useAnimatedAction } from './use-animated-action.js';
+export { actionSheetContainer, actionSheetList, actionSheetRow, } from './action-sheet.js';
+export { Ripple, rippleAnimation, useRipple } from './ripple.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"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;AAE7D,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,cAAc,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/ripple.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Material-style ripple — a domain-free press-feedback overlay.
+ *
+ * Two pieces that work together:
+ * - `useRipple<T>()` — a pure React hook that tracks the active ripple's
+ *   position and which target fired it. `trigger(event, target)` records the
+ *   click point relative to the element; `isTarget(value)` tells a given
+ *   element whether it owns the current ripple.
+ * - `Ripple` — a styled `<span>` placed inside the (relatively-positioned)
+ *   pressable element. Give it `key={ripple.key}` so each press restarts the
+ *   animation, and `$x`/`$y` from the ripple state.
+ *
+ * The fill reads `theme.colors.ripple` (a generic styling token, not app
+ * domain) and falls back to `rgba(0, 0, 0, 0.1)` when absent — so it works with
+ * or without a themed `ThemeProvider`.
+ *
+ * `styled-components` is an optional peer dependency, used only by this module;
+ * consumers that import only the press / action-sheet string primitives never
+ * pull it in.
+ */
+import { type MouseEvent } from 'react';
+export interface RippleState<T> {
+    x: number;
+    y: number;
+    key: number;
+    target: T;
+}
+export declare const rippleAnimation: import("styled-components/dist/models/Keyframes").default;
+export declare const Ripple: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "$x" | "$y"> & {
+    $x: number;
+    $y: number;
+}, never> & Partial<Pick<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "$x" | "$y"> & {
+    $x: number;
+    $y: number;
+}, never>>> & string;
+export declare function useRipple<T>(): {
+    ripple: RippleState<T> | null;
+    trigger: (e: MouseEvent<HTMLElement>, target: T) => void;
+    isTarget: (value: T) => boolean;
+};
+//# sourceMappingURL=ripple.d.ts.map

package/dist/ripple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple.d.ts","sourceRoot":"","sources":["../src/ripple.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC;AAM/D,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,CAAC;CACV;AAED,eAAO,MAAM,eAAe,2DAS3B,CAAC;AAEF,eAAO,MAAM,MAAM;QAAqB,MAAM;QAAM,MAAM;;QAAlB,MAAM;QAAM,MAAM;oBAazD,CAAC;AAEF,wBAAgB,SAAS,CAAC,CAAC;;iBAGM,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC;sBAWzD,CAAC;EAKV"}

package/dist/ripple.js

@@ -0,0 +1,63 @@
+/**
+ * Material-style ripple — a domain-free press-feedback overlay.
+ *
+ * Two pieces that work together:
+ * - `useRipple<T>()` — a pure React hook that tracks the active ripple's
+ *   position and which target fired it. `trigger(event, target)` records the
+ *   click point relative to the element; `isTarget(value)` tells a given
+ *   element whether it owns the current ripple.
+ * - `Ripple` — a styled `<span>` placed inside the (relatively-positioned)
+ *   pressable element. Give it `key={ripple.key}` so each press restarts the
+ *   animation, and `$x`/`$y` from the ripple state.
+ *
+ * The fill reads `theme.colors.ripple` (a generic styling token, not app
+ * domain) and falls back to `rgba(0, 0, 0, 0.1)` when absent — so it works with
+ * or without a themed `ThemeProvider`.
+ *
+ * `styled-components` is an optional peer dependency, used only by this module;
+ * consumers that import only the press / action-sheet string primitives never
+ * pull it in.
+ */
+import { useCallback, useState } from 'react';
+// Named imports (not the default) so this resolves consistently across bundler
+// and raw ESM/CJS environments — styled-components v6's default export is the
+// CJS namespace under Node's interop, where `styled.span` is undefined.
+import { styled, keyframes } from 'styled-components';
+export const rippleAnimation = keyframes `
+	0% {
+		transform: scale(0);
+		opacity: 0.6;
+	}
+	100% {
+		transform: scale(10);
+		opacity: 0;
+	}
+`;
+export const Ripple = styled.span `
+	position: absolute;
+	left: ${({ $x }) => $x}px;
+	top: ${({ $y }) => $y}px;
+	width: 50px;
+	height: 50px;
+	margin-left: -25px;
+	margin-top: -25px;
+	border-radius: 50%;
+	background-color: ${({ theme }) => theme?.colors?.ripple ?? 'rgba(0, 0, 0, 0.1)'};
+	pointer-events: none;
+	animation: ${rippleAnimation} 0.4s ease-out forwards;
+`;
+export function useRipple() {
+    const [ripple, setRipple] = useState(null);
+    const trigger = useCallback((e, target) => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        setRipple({
+            x: e.clientX - rect.left,
+            y: e.clientY - rect.top,
+            key: Date.now(),
+            target,
+        });
+    }, []);
+    const isTarget = useCallback((value) => ripple !== null && ripple.target === value, [ripple]);
+    return { ripple, trigger, isTarget };
+}
+//# sourceMappingURL=ripple.js.map

package/dist/ripple.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple.js","sourceRoot":"","sources":["../src/ripple.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAmB,MAAM,OAAO,CAAC;AAC/D,+EAA+E;AAC/E,8EAA8E;AAC9E,wEAAwE;AACxE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAStD,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAA;;;;;;;;;CASvC,CAAC;AAEF,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAA4B;;SAEpD,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;QACf,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;;;;;;qBAMD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAChC,KAA0C,EAAE,MAAM,EAAE,MAAM,IAAI,oBAAoB;;cAEvE,eAAe;CAC5B,CAAC;AAEF,MAAM,UAAU,SAAS;IACxB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAwB,IAAI,CAAC,CAAC;IAElE,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAA0B,EAAE,MAAS,EAAE,EAAE;QACrE,MAAM,IAAI,GAAG,CAAC,CAAC,aAAa,CAAC,qBAAqB,EAAE,CAAC;QACrD,SAAS,CAAC;YACT,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI;YACxB,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG;YACvB,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;YACf,MAAM;SACN,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,QAAQ,GAAG,WAAW,CAC3B,CAAC,KAAQ,EAAE,EAAE,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,EACxD,CAAC,MAAM,CAAC,CACR,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kang-components",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Generic, domain-free React UI primitives (CSS-first press feedback, delayed-action hook).",
 	"type": "module",
 	"license": "MIT",
@@ -26,16 +26,21 @@
 		"prepublishOnly": "npm run build"
 	},
 	"peerDependencies": {
-		"react": ">=18"
+		"react": ">=18",
+		"styled-components": ">=6"
 	},
 	"peerDependenciesMeta": {
 		"react": {
 			"optional": true
+		},
+		"styled-components": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@types/react": "^18.3.18",
 		"react": "^18.3.1",
+		"styled-components": "^6.1.16",
 		"typescript": "~5.6.2"
 	}
 }