@base-ripple/react 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# @base-ripple/react
+
+React wrapper for Base Ripple. Use this package when you want a declarative
+component that attaches the ripple behavior from `@base-ripple/core`.
+
+Demo: <https://base-ripple.vercel.app/>
+
+## Install
+
+```bash
+npm i @base-ripple/react
+```
+
+## Quick start (React)
+
+```tsx
+"use client";
+
+import "@base-ripple/react/styles.css";
+import { BaseRipple } from "@base-ripple/react";
+
+export function Example() {
+  return <BaseRipple className="base-ripple-container">Click me</BaseRipple>;
+}
+```
+
+You still need to define a fill color and opacity for the ripple:
+
+```css
+.base-ripple {
+  background: currentColor;
+  opacity: 0.12;
+}
+```
+
+## Styles (required)
+
+The ripple uses two class names:
+
+- `.base-ripple-container` on the target element
+- `.base-ripple` on the injected `<span>`
+
+Option A: Import the default styles (recommended)
+
+```css
+@import "@base-ripple/react/styles.css";
+```
+
+Option B: Provide your own styles (advanced)
+
+If you do not import `styles.css`, create your own CSS using the same class
+names. Make sure the container is positioned and clips overflow. Here is the
+default `styles.css` you can copy and customize:
+
+```css
+.base-ripple-container {
+  position: relative;
+  overflow: hidden;
+  touch-action: manipulation;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.base-ripple {
+  position: absolute;
+  top: 0;
+  left: 0;
+  border-radius: 50%;
+  pointer-events: none;
+  animation: baseRipple 600ms cubic-bezier(0.4, 0, 0.2, 1) forwards;
+  transition: opacity 600ms cubic-bezier(0.4, 0, 0.2, 1);
+  will-change: transform, opacity;
+}
+
+@keyframes baseRipple {
+  from {
+    transform: translate3d(
+        calc(var(--base-ripple-keyframes-from-x) - 50%),
+        calc(var(--base-ripple-keyframes-from-y) - 50%),
+        0
+      )
+      scale(0);
+  }
+  to {
+    transform: translate3d(
+        calc(var(--base-ripple-keyframes-to-x) - 50%),
+        calc(var(--base-ripple-keyframes-to-y) - 50%),
+        0
+      )
+      scale(1);
+  }
+}
+```
+
+IMPORTANT: If you write your own `.base-ripple` styles, it MUST include a
+`transition` for `opacity`. Cleanup relies on the `transitionend` event for
+`opacity`. Without it, ripple elements never remove themselves. If you want no
+transition, set a `transition` with 0 duration, for example:
+
+```css
+.base-ripple {
+  transition: opacity 0ms linear;
+}
+```
+
+## API
+
+```tsx
+import { BaseRipple } from "@base-ripple/react";
+
+<BaseRipple
+  as="button"
+  className="base-ripple-container"
+  rippleOptions={{ origin: "pointer", sizeOffset: 96 }}
+>
+  Click me
+</BaseRipple>;
+```
+
+### Props
+
+| Prop            | Type                      | Default  | Description                                           |
+| --------------- | ------------------------- | -------- | ----------------------------------------------------- |
+| `as`            | `ElementType`             | `button` | Underlying element to render.                         |
+| `rippleOptions` | `AttachBaseRippleOptions` | `{}`     | Options passed to the core `attachBaseRipple` helper. |
+
+All other props are passed through to the underlying element, and the `ref` is
+forwarded to the rendered element.
+
+### `rippleOptions`
+
+| Prop         | Type                     | Default     | Description                                                                                            |
+| ------------ | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------ |
+| `origin`     | `"pointer" \| "center"`  | `pointer`   | Where the ripple starts. `pointer` uses the pointer position; `center` starts from the element center. |
+| `sizeOffset` | `number`                 | `0`         | Extra pixels added to the ripple diameter, useful when adding blur or glow.                            |
+| `attributes` | `Record<string, string>` | `undefined` | Extra attributes added to each ripple `<span>`.                                                        |
+
+## Behavior notes
+
+- Uses pointer and keyboard interactions (Space, Enter, NumpadEnter).
+- Respects `prefers-reduced-motion` by disabling ripples and clearing existing.
+- Skips ripples for disabled elements (`disabled` or `aria-disabled="true"`).
+- Adds `aria-hidden="true"` to the ripple spans for accessibility.
+- Browser-only API; use inside client components.
+
+## Core package
+
+If you need the DOM API or want to build your own wrapper, use the core package:
+
+- `@base-ripple/core`
+
+## Planned framework wrappers (not implemented yet)
+
+- Preact
+- Vue
+- Svelte
+- Solid
+- Angular
+- Lit
+- Qwik

package/dist/assets/styles-DuOh9mGm.css

@@ -0,0 +1 @@
+.base-ripple-container{touch-action:manipulation;-webkit-tap-highlight-color:transparent;position:relative;overflow:hidden}.base-ripple{pointer-events:none;will-change:transform,opacity;border-radius:50%;transition:opacity .6s cubic-bezier(.4,0,.2,1);animation:.6s cubic-bezier(.4,0,.2,1) forwards baseRipple;position:absolute;top:0;left:0}@keyframes baseRipple{0%{transform:translate3d(calc(var(--base-ripple-keyframes-from-x) - 50%),calc(var(--base-ripple-keyframes-from-y) - 50%),0)scale(0)}to{transform:translate3d(calc(var(--base-ripple-keyframes-to-x) - 50%),calc(var(--base-ripple-keyframes-to-y) - 50%),0)scale(1)}}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./lib/base-ripple.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,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./lib/base-ripple.js";

package/dist/lib/base-ripple.d.ts

@@ -0,0 +1,17 @@
+import { AttachBaseRippleOptions } from "@base-ripple/core";
+import { ComponentPropsWithoutRef, ComponentPropsWithRef, ElementType, ReactElement } from "react";
+type PolymorphicAs<E extends ElementType> = {
+    as?: E;
+};
+type PolymorphicOmit<E extends ElementType, P> = keyof (PolymorphicAs<E> & P);
+type PolymorphicComponentProps<E extends ElementType, P> = P & PolymorphicAs<E> & Omit<ComponentPropsWithoutRef<E>, PolymorphicOmit<E, P>>;
+type PolymorphicComponentRef<E extends ElementType> = ComponentPropsWithRef<E>["ref"];
+type RippleProps = {
+    rippleOptions?: AttachBaseRippleOptions;
+};
+type RippleComponent = <E extends ElementType = "button">(props: PolymorphicComponentProps<E, RippleProps> & {
+    ref?: PolymorphicComponentRef<E>;
+}) => ReactElement | null;
+export declare const BaseRipple: RippleComponent;
+export {};
+//# sourceMappingURL=base-ripple.d.ts.map

package/dist/lib/base-ripple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-ripple.d.ts","sourceRoot":"","sources":["../../src/lib/base-ripple.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAoB,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EAGX,YAAY,EAMb,MAAM,OAAO,CAAC;AAIf,KAAK,aAAa,CAAC,CAAC,SAAS,WAAW,IAAI;IAAE,EAAE,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEvD,KAAK,eAAe,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE9E,KAAK,yBAAyB,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,IAAI,CAAC,GAC1D,aAAa,CAAC,CAAC,CAAC,GAChB,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE3D,KAAK,uBAAuB,CAAC,CAAC,SAAS,WAAW,IAChD,qBAAqB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAElC,KAAK,WAAW,GAAG;IACjB,aAAa,CAAC,EAAE,uBAAuB,CAAC;CACzC,CAAC;AAEF,KAAK,eAAe,GAAG,CAAC,CAAC,SAAS,WAAW,GAAG,QAAQ,EACtD,KAAK,EAAE,yBAAyB,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG;IACjD,GAAG,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;CAClC,KACE,YAAY,GAAG,IAAI,CAAC;AA0BzB,eAAO,MAAM,UAAU,EAAyB,eAAe,CAAC"}

package/dist/lib/base-ripple.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { attachBaseRipple } from "@base-ripple/core";
+import { forwardRef, useCallback, useEffect, useRef, } from "react";
+// endregion TYPES
+// region MAIN
+const DEFAULT_RIPPLE_OPTIONS = {};
+function Ripple({ rippleOptions = DEFAULT_RIPPLE_OPTIONS, as: Component = "button", ...restProps }, ref) {
+    const localRef = useRef(null);
+    const mergedRef = useMergedRefs(ref, localRef);
+    useEffect(() => {
+        if (!localRef.current)
+            return;
+        return attachBaseRipple(localRef.current, rippleOptions);
+    }, [serializeOptions(rippleOptions)]);
+    return _jsx(Component, { ref: mergedRef, ...restProps });
+}
+export const BaseRipple = forwardRef(Ripple);
+function setRef(ref, value) {
+    if (!ref)
+        return;
+    if (typeof ref === "function") {
+        ref(value);
+        return;
+    }
+    try {
+        ref.current = value;
+    }
+    catch {
+        // in extremely rare cases (e.g. read-only refs), ignore.
+    }
+}
+function useMergedRefs(...refs) {
+    const refsRef = useRef(refs);
+    useEffect(() => {
+        refsRef.current = refs;
+    }, refs);
+    return useCallback((node) => {
+        for (const ref of refsRef.current)
+            setRef(ref, node);
+    }, []);
+}
+// endregion USE MERGED REFS
+// region OTHER UTILITIES
+function serializeOptions(options) {
+    if (!options)
+        return "";
+    const attributes = options.attributes;
+    const serializedAttributes = attributes
+        ? Object.keys(attributes)
+            .sort()
+            .map((key) => `${encodeURIComponent(key)}:${encodeURIComponent(attributes[key])}`)
+            .join("|")
+        : "";
+    return `${options.origin ?? ""}__${options.sizeOffset ?? ""}__${serializedAttributes}`;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@base-ripple/react",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@base-ripple/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "sideEffects": [
+    "./src/styles.css"
+  ],
+  "files": [
+    "src/styles.css",
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@base-ripple/core": "1.0.0",
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8 <20"
+  },
+  "nx": {
+    "tags": [
+      "scope:react"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/styles.css

@@ -0,0 +1 @@
+@import "@base-ripple/core/styles.css";