@base-ripple/core 1.0.0

package/README.md

@@ -0,0 +1,165 @@
+# @base-ripple/core
+
+Framework-agnostic ripple effect for DOM elements. Use this core package for
+vanilla JS or to build your own wrapper. If you are using a framework, prefer
+the framework-specific package (for example `@base-ripple/react`).
+
+Demo: <https://base-ripple.vercel.app/>
+
+## Install
+
+```bash
+npm i @base-ripple/core
+```
+
+## Quick start (vanilla)
+
+```html
+<button class="base-ripple-container">Click me</button>
+```
+
+```ts
+import "@base-ripple/core/styles.css";
+import { attachBaseRipple } from "@base-ripple/core";
+
+const button = document.querySelector<HTMLButtonElement>(
+  ".base-ripple-container",
+);
+if (!button) throw new Error("Missing button");
+
+const dispose = attachBaseRipple(button, {
+  origin: "pointer",
+  sizeOffset: 96,
+  attributes: { "data-ripple": "true" },
+});
+
+// later
+dispose();
+```
+
+The ripple attaches listeners to the target element and global pointer events.
+Call the returned `dispose` function on teardown.
+
+## 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/core/styles.css";
+```
+
+The default stylesheet handles layout and animation. You still need to set a
+fill color and opacity, for example:
+
+```css
+.base-ripple {
+  background: currentColor;
+  opacity: 0.12;
+}
+```
+
+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
+
+```ts
+import type { AttachBaseRippleOptions } from "@base-ripple/core";
+
+attachBaseRipple(
+  container: HTMLElement,
+  options?: AttachBaseRippleOptions
+): () => void;
+```
+
+### Options
+
+| 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; call it after the DOM is available.
+
+## Framework packages
+
+Use the framework-specific package when available:
+
+- React: `@base-ripple/react`
+
+This core package is ideal for vanilla usage or custom integrations.
+
+## Planned framework wrappers (not implemented yet)
+
+- Preact
+- Vue
+- Svelte
+- Solid
+- Angular
+- Lit
+- Qwik

package/dist/index.js

@@ -0,0 +1,179 @@
+const f = /* @__PURE__ */ new Set();
+let m = !1;
+function S() {
+  m || (m = !0, addEventListener("blur", c), addEventListener("pagehide", c), addEventListener("beforeunload", c), addEventListener("pointerup", h, { passive: !0 }), addEventListener("pointercancel", h, { passive: !0 }), document.addEventListener("visibilitychange", B));
+}
+function N() {
+  !m || f.size > 0 || (m = !1, removeEventListener("blur", c), removeEventListener("pagehide", c), removeEventListener("beforeunload", c), removeEventListener("pointerup", h), removeEventListener("pointercancel", h), document.removeEventListener("visibilitychange", B));
+}
+function c() {
+  for (const e of f)
+    e.fadeAll();
+}
+function h(e) {
+  for (const i of f)
+    i.fadeFromPointer(e);
+}
+function B() {
+  document.visibilityState === "hidden" && c();
+}
+function _(e, {
+  origin: i = "pointer",
+  sizeOffset: s = 0,
+  attributes: n
+} = {}) {
+  const a = /* @__PURE__ */ new Set(), o = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Map(), b = i === "pointer";
+  let v = !1, u = O();
+  const g = (t, r, l) => ({
+    from: {
+      size: 0,
+      x: r,
+      y: l
+    },
+    to: {
+      size: (b ? Q(
+        t.width,
+        t.height,
+        r,
+        l
+      ) : K(
+        t.width,
+        t.height
+      )) + s,
+      x: b ? r : t.width / 2,
+      y: b ? l : t.height / 2
+    }
+  }), x = (t) => {
+    if (t.defaultPrevented || I(e) || u) return;
+    const r = e.getBoundingClientRect(), l = g(
+      r,
+      t.clientX - r.x,
+      t.clientY - r.y
+    ), p = D({
+      rippleKeyframes: l,
+      removeHandler: R,
+      attributes: n
+    });
+    a.add(p), o.set(t.pointerId, p), e.appendChild(p);
+  }, w = (t) => {
+    if (t.defaultPrevented || I(e) || u || t.repeat || d.has(t.code) || !F(t.code) || q(t.target)) return;
+    const r = e.getBoundingClientRect(), l = g(
+      r,
+      r.width / 2,
+      r.height / 2
+    ), p = D({
+      rippleKeyframes: l,
+      removeHandler: R,
+      attributes: n
+    });
+    a.add(p), d.set(t.code, p), e.appendChild(p);
+  }, y = (t) => {
+    t.style.opacity = "0";
+  }, E = (t) => {
+    const r = o.get(t.pointerId);
+    r && (y(r), o.delete(t.pointerId));
+  }, z = (t) => {
+    const r = d.get(t.code);
+    r && (y(r), d.delete(t.code));
+  }, L = () => {
+    for (const t of o.values()) y(t);
+    o.clear();
+    for (const t of d.values()) y(t);
+    d.clear();
+  }, R = (t) => {
+    a.delete(t);
+    for (const [r, l] of o)
+      if (l === t) {
+        o.delete(r);
+        break;
+      }
+    for (const [r, l] of d)
+      if (l === t) {
+        d.delete(r);
+        break;
+      }
+    t.remove();
+  }, P = () => {
+    for (const t of a)
+      t.remove();
+    a.clear(), o.clear(), d.clear();
+  }, M = () => {
+    v || (e.addEventListener("pointerdown", x, {
+      passive: !0
+    }), v = !0);
+  }, k = () => {
+    v && (e.removeEventListener("pointerdown", x), v = !1);
+  }, G = T((t) => {
+    u !== t && (u = t, u ? (k(), P()) : M());
+  }), A = (t) => {
+    F(t.code) && z(t);
+  };
+  u || M(), e.addEventListener("keyup", A), e.addEventListener("keydown", w), e.addEventListener("contextmenu", L), e.addEventListener("pointerleave", E, {
+    passive: !0
+  }), S();
+  const C = {
+    fadeAll: L,
+    fadeFromPointer: E
+  };
+  return f.add(C), () => {
+    G(), k(), e.removeEventListener("keyup", A), e.removeEventListener("keydown", w), e.removeEventListener("contextmenu", L), e.removeEventListener("pointerleave", E), f.delete(C), N(), P();
+  };
+}
+const H = "(prefers-reduced-motion: reduce)";
+function O() {
+  return typeof matchMedia != "function" ? !1 : matchMedia(H).matches;
+}
+function T(e) {
+  if (typeof matchMedia != "function") return () => {
+  };
+  const i = matchMedia(H), s = (n) => e(n.matches);
+  return typeof i.addEventListener == "function" ? (i.addEventListener("change", s), () => i.removeEventListener("change", s)) : typeof i.addListener == "function" ? (i.addListener(s), () => i.removeListener(s)) : () => {
+  };
+}
+function D({
+  rippleKeyframes: e,
+  removeHandler: i,
+  attributes: s
+}) {
+  const n = document.createElement("span");
+  if (n.setAttribute("aria-hidden", "true"), n.className = "base-ripple", n.style.width = e.to.size + "px", n.style.height = e.to.size + "px", n.style.setProperty(
+    "--base-ripple-keyframes-from-x",
+    e.from.x + "px"
+  ), n.style.setProperty(
+    "--base-ripple-keyframes-from-y",
+    e.from.y + "px"
+  ), n.style.setProperty(
+    "--base-ripple-keyframes-to-x",
+    e.to.x + "px"
+  ), n.style.setProperty(
+    "--base-ripple-keyframes-to-y",
+    e.to.y + "px"
+  ), s)
+    for (const [o, d] of Object.entries(s))
+      n.setAttribute(o, d);
+  const a = (o) => {
+    o.propertyName === "opacity" && (i(n), n.removeEventListener("transitionend", a));
+  };
+  return n.addEventListener("transitionend", a), n;
+}
+function I(e) {
+  const i = e.getAttribute("aria-disabled");
+  return i !== null ? i.toLowerCase() === "true" : "disabled" in e && !!e.disabled;
+}
+function F(e) {
+  return e === "Space" || e === "Enter" || e === "NumpadEnter";
+}
+const U = 'input:not([type]),input[type="text"],input[type="search"],input[type="url"],input[type="tel"],input[type="email"],input[type="password"],input[type="number"],input[type="date"],input[type="time"],input[type="datetime-local"],input[type="month"],input[type="week"],textarea,[contenteditable]';
+function q(e) {
+  return e instanceof Element ? !!e.closest(U) : !1;
+}
+function K(e, i) {
+  return Math.sqrt(e * e + i * i);
+}
+function Q(e, i, s, n) {
+  const a = Math.max(s, e - s), o = Math.max(n, i - n);
+  return 2 * Math.sqrt(a * a + o * o);
+}
+export {
+  _ as attachBaseRipple
+};

package/dist/styles.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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@base-ripple/core",
+  "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": {
+      "@base-ripple/source": "./src/styles.css",
+      "default": "./dist/styles.css"
+    }
+  },
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:core"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}