@mizuui/liquid-glass-core 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# mizuui-liquid-glass-core
+
+The rendering engine behind the liquid glass effect. No framework, no build step — plain ESM.
+
+It generates a displacement map for a rounded rectangle and feeds it to an SVG
+`feDisplacementMap` that runs inside `backdrop-filter`, so the content behind the
+element is genuinely refracted through a bevel. There is no blur by default: this
+is glass, not frost.
+
+```bash
+npm install mizuui-liquid-glass-core
+```
+
+```js
+import { createLiquidGlass } from "mizuui-liquid-glass-core";
+
+const glass = createLiquidGlass(document.querySelector("#panel"), {
+  radius: 28,
+  depth: 12,
+  strength: 70,
+});
+
+glass.update({ strength: 100 });
+glass.destroy();
+```
+
+## Options
+
+| Option                | Default | Description                                             |
+| --------------------- | ------- | ------------------------------------------------------- |
+| `radius`              | `24`    | Corner radius in px.                                    |
+| `depth`               | `10`    | Thickness of the refracting bevel in px.                |
+| `strength`            | `60`    | Maximum backdrop displacement in px.                    |
+| `falloff`             | `2`     | Bevel curve. Higher pushes the bend towards the edge.   |
+| `chromaticAberration` | `3`     | Per-channel offset in px.                               |
+| `blur`                | `0`     | Backdrop blur. Anything above 0 starts looking frosted. |
+| `saturation`          | `1.6`   | Backdrop saturation multiplier.                         |
+| `brightness`          | `1.04`  | Backdrop brightness multiplier.                         |
+| `specular`            | `1`     | Specular rim intensity, `0` disables it.                |
+| `resolution`          | `512`   | Max pixel size of the generated displacement map.       |
+| `fallbackBlur`        | `8`     | Blur used where SVG backdrop filters are unsupported.   |
+
+The instance resizes itself via `ResizeObserver`; call `refresh()` if you move it
+in a way that observer cannot see.
+
+## Browser support
+
+`backdrop-filter: url(#filter)` currently works in Chromium. Safari and Firefox
+fall back to `fallbackBlur` plus the specular rim.

package/index.d.ts

@@ -0,0 +1,38 @@
+export interface LiquidGlassOptions {
+  radius?: number
+  depth?: number
+  strength?: number
+  falloff?: number
+  chromaticAberration?: number
+  blur?: number
+  saturation?: number
+  brightness?: number
+  specular?: number
+  resolution?: number
+  fallbackBlur?: number
+}
+
+export interface LiquidGlassInstance {
+  readonly options: Required<LiquidGlassOptions>
+  update(options: LiquidGlassOptions): void
+  refresh(): void
+  destroy(): void
+}
+
+export declare const defaultOptions: Required<LiquidGlassOptions>
+
+export declare function createLiquidGlass(
+  element: HTMLElement,
+  options?: LiquidGlassOptions,
+): LiquidGlassInstance
+
+export declare function createDisplacementMap(options: {
+  width: number
+  height: number
+  radius?: number
+  depth?: number
+  falloff?: number
+  resolution?: number
+}): { href: string; width: number; height: number }
+
+export declare function injectStyles(): void

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mizuui/liquid-glass-core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic liquid glass (real backdrop refraction, not frosted blur).",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "liquid-glass",
+    "glassmorphism",
+    "refraction",
+    "backdrop-filter",
+    "svg-filter"
+  ]
+}

package/src/displacement.js

@@ -0,0 +1,92 @@
+const clamp = (value, min, max) => (value < min ? min : value > max ? max : value)
+
+/**
+ * Signed distance (negative = inside) to a rounded rectangle centred on the
+ * origin, plus the outward-pointing unit normal at that point.
+ */
+function roundedRectSDF(px, py, halfWidth, halfHeight, radius) {
+  const qx = Math.abs(px) - (halfWidth - radius)
+  const qy = Math.abs(py) - (halfHeight - radius)
+  const mx = Math.max(qx, 0)
+  const my = Math.max(qy, 0)
+  const len = Math.hypot(mx, my)
+  const distance = Math.min(Math.max(qx, qy), 0) + len - radius
+
+  const sx = px < 0 ? -1 : 1
+  const sy = py < 0 ? -1 : 1
+
+  let nx
+  let ny
+  if (len > 0) {
+    nx = (sx * mx) / len
+    ny = (sy * my) / len
+  } else if (qx > qy) {
+    nx = sx
+    ny = 0
+  } else {
+    nx = 0
+    ny = sy
+  }
+
+  return { distance, nx, ny }
+}
+
+/**
+ * Renders the refraction map consumed by `feDisplacementMap`.
+ *
+ * Red encodes the horizontal offset, green the vertical one, both biased around
+ * 128 (= no displacement). The offset ramps up towards the edges of the rounded
+ * rectangle so the backdrop is bent like it would be by a thick glass bevel.
+ *
+ * @returns {{ href: string, width: number, height: number }}
+ */
+export function createDisplacementMap({
+  width,
+  height,
+  radius = 24,
+  depth = 8,
+  falloff = 2,
+  resolution = 512,
+}) {
+  const aspectScale = Math.min(1, resolution / Math.max(width, height, 1))
+  const w = Math.max(1, Math.round(width * aspectScale))
+  const h = Math.max(1, Math.round(height * aspectScale))
+
+  const canvas = document.createElement('canvas')
+  canvas.width = w
+  canvas.height = h
+
+  const ctx = canvas.getContext('2d')
+  const image = ctx.createImageData(w, h)
+  const data = image.data
+
+  const halfW = w / 2
+  const halfH = h / 2
+  const r = clamp(radius * aspectScale, 0, Math.min(halfW, halfH))
+  const edge = clamp(depth * aspectScale, 0.5, Math.min(halfW, halfH))
+  const curve = Math.max(0.1, falloff)
+
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const px = x + 0.5 - halfW
+      const py = y + 0.5 - halfH
+      const { distance, nx, ny } = roundedRectSDF(px, py, halfW, halfH, r)
+
+      let amount = 0
+      if (distance < 0) {
+        const inset = -distance
+        amount = Math.pow(1 - clamp(inset / edge, 0, 1), curve)
+      }
+
+      const i = (y * w + x) * 4
+      data[i] = clamp(Math.round(128 + nx * amount * 127), 0, 255)
+      data[i + 1] = clamp(Math.round(128 + ny * amount * 127), 0, 255)
+      data[i + 2] = 128
+      data[i + 3] = 255
+    }
+  }
+
+  ctx.putImageData(image, 0, 0)
+
+  return { href: canvas.toDataURL(), width: w, height: h }
+}

package/src/filter.js

@@ -0,0 +1,136 @@
+const SVG_NS = 'http://www.w3.org/2000/svg'
+const XLINK_NS = 'http://www.w3.org/1999/xlink'
+
+let defsHost = null
+
+function getHost() {
+  if (defsHost && defsHost.isConnected) return defsHost
+
+  defsHost = document.createElementNS(SVG_NS, 'svg')
+  defsHost.setAttribute('aria-hidden', 'true')
+  defsHost.setAttribute('focusable', 'false')
+  defsHost.dataset.liquidGlass = 'filters'
+  defsHost.style.cssText =
+    'position:absolute;width:0;height:0;overflow:hidden;pointer-events:none;'
+  document.body.appendChild(defsHost)
+
+  return defsHost
+}
+
+function el(name, attrs) {
+  const node = document.createElementNS(SVG_NS, name)
+  for (const key in attrs) node.setAttribute(key, attrs[key])
+  return node
+}
+
+/** Keeps only one colour channel, optionally discarding alpha so passes can be summed. */
+function channelMatrix(channel, keepAlpha) {
+  const rows = {
+    r: '1 0 0 0 0  0 0 0 0 0  0 0 0 0 0',
+    g: '0 0 0 0 0  0 1 0 0 0  0 0 0 0 0',
+    b: '0 0 0 0 0  0 0 0 0 0  0 0 1 0 0',
+  }
+  return `${rows[channel]}  0 0 0 ${keepAlpha ? 1 : 0} 0`
+}
+
+/**
+ * Creates an SVG filter that refracts whatever is behind the element.
+ * Returns a handle used by the glass controller.
+ */
+export function createGlassFilter(id) {
+  const filter = el('filter', {
+    id,
+    'color-interpolation-filters': 'sRGB',
+    x: '0',
+    y: '0',
+    width: '100%',
+    height: '100%',
+  })
+  getHost().appendChild(filter)
+
+  return {
+    url: `url(#${id})`,
+
+    update({ map, scale, aberration, blur }) {
+      filter.replaceChildren()
+
+      const image = el('feImage', {
+        result: 'map',
+        preserveAspectRatio: 'none',
+        x: '0',
+        y: '0',
+        width: String(map.displayWidth),
+        height: String(map.displayHeight),
+      })
+      image.setAttribute('href', map.href)
+      image.setAttributeNS(XLINK_NS, 'xlink:href', map.href)
+      filter.appendChild(image)
+
+      const displace = (scaleValue, result) =>
+        el('feDisplacementMap', {
+          in: 'SourceGraphic',
+          in2: 'map',
+          scale: String(scaleValue),
+          xChannelSelector: 'R',
+          yChannelSelector: 'G',
+          result,
+        })
+
+      let last = 'refracted'
+
+      if (aberration > 0) {
+        const channels = [
+          ['r', scale + aberration],
+          ['g', scale],
+          ['b', scale - aberration],
+        ]
+
+        channels.forEach(([channel, channelScale], index) => {
+          filter.appendChild(displace(channelScale, `pass-${channel}`))
+          filter.appendChild(
+            el('feColorMatrix', {
+              in: `pass-${channel}`,
+              type: 'matrix',
+              values: channelMatrix(channel, index === 0),
+              result: `channel-${channel}`,
+            }),
+          )
+        })
+
+        filter.appendChild(
+          el('feComposite', {
+            in: 'channel-r',
+            in2: 'channel-g',
+            operator: 'arithmetic',
+            k2: '1',
+            k3: '1',
+            result: 'rg',
+          }),
+        )
+        filter.appendChild(
+          el('feComposite', {
+            in: 'rg',
+            in2: 'channel-b',
+            operator: 'arithmetic',
+            k2: '1',
+            k3: '1',
+            result: 'refracted',
+          }),
+        )
+      } else {
+        filter.appendChild(displace(scale, 'refracted'))
+      }
+
+      if (blur > 0) {
+        filter.appendChild(
+          el('feGaussianBlur', { in: last, stdDeviation: String(blur), result: 'blurred' }),
+        )
+        last = 'blurred'
+      }
+    },
+
+    destroy() {
+      filter.remove()
+    },
+  }
+}

package/src/glass.js

@@ -0,0 +1,137 @@
+import { createDisplacementMap } from './displacement.js'
+import { createGlassFilter } from './filter.js'
+import { injectStyles } from './styles.js'
+
+export const defaultOptions = {
+  /** Corner radius in px. Keep in sync with any border-radius you set yourself. */
+  radius: 30,
+  /** Thickness of the refracting bevel in px. */
+  depth: 35,
+  /** Maximum backdrop displacement in px. This is the strength of the lensing. */
+  strength: 120,
+  /** Falloff curve of the bevel. Higher = the bend is pushed closer to the edge. */
+  falloff: 2,
+  /** Per-channel offset in px. Gives the prism fringe real glass has. */
+  chromaticAberration: 0,
+  /** Backdrop blur in px. Leave at 0 — blur is frosted glass, not liquid glass. */
+  blur: 15,
+  /** Backdrop saturation multiplier. */
+  saturation: 3,
+  /** Backdrop brightness multiplier. */
+  brightness: 1.04,
+  /** Specular rim intensity, 0 disables it. */
+  specular: 1,
+  /** Max pixel size of the generated displacement map. */
+  resolution: 512,
+  /** Blur used when the browser cannot run SVG filters in a backdrop-filter. */
+  fallbackBlur: 8,
+}
+
+let uid = 0
+
+function supportsBackdropFilterUrl() {
+  if (typeof CSS === 'undefined' || !CSS.supports) return false
+  // Firefox parses backdrop-filter but silently drops url() references.
+  return (
+    CSS.supports('backdrop-filter', 'url(#x)') &&
+    !/\bGecko\/\b/.test(navigator.userAgent ?? '')
+  )
+}
+
+/**
+ * Turns an element into a pane of liquid glass: everything behind it is
+ * refracted through a generated bevel instead of being blurred.
+ *
+ * @param {HTMLElement} element
+ * @param {Partial<typeof defaultOptions>} [options]
+ */
+export function createLiquidGlass(element, options = {}) {
+  injectStyles()
+
+  let config = { ...defaultOptions, ...options }
+  let destroyed = false
+  let frame = 0
+
+  const useFilter = supportsBackdropFilterUrl()
+  const filter = useFilter ? createGlassFilter(`liquid-glass-${++uid}`) : null
+
+  element.classList.add('liquid-glass')
+
+  function applyBackdrop() {
+    const layers = []
+    if (config.brightness !== 1) layers.push(`brightness(${config.brightness})`)
+    if (config.saturation !== 1) layers.push(`saturate(${config.saturation})`)
+
+    if (filter) {
+      if (config.blur > 0) layers.push(`blur(${config.blur}px)`)
+      layers.push(filter.url)
+    } else if (config.fallbackBlur > 0) {
+      layers.push(`blur(${config.fallbackBlur}px)`)
+    }
+
+    element.style.setProperty('--lg-backdrop', layers.join(' ') || 'none')
+    element.style.setProperty('--lg-radius', `${config.radius}px`)
+    element.style.setProperty('--lg-specular', String(config.specular))
+  }
+
+  function render() {
+    frame = 0
+    if (destroyed || !filter) return
+
+    const { width, height } = element.getBoundingClientRect()
+    if (width < 1 || height < 1) return
+
+    const map = createDisplacementMap({
+      width,
+      height,
+      radius: config.radius,
+      depth: config.depth,
+      falloff: config.falloff,
+      resolution: config.resolution,
+    })
+
+    filter.update({
+      map: { ...map, displayWidth: width, displayHeight: height },
+      scale: config.strength,
+      aberration: config.chromaticAberration,
+      blur: 0,
+    })
+  }
+
+  function schedule() {
+    if (destroyed || frame) return
+    frame = requestAnimationFrame(render)
+  }
+
+  const observer = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null
+  observer?.observe(element)
+
+  applyBackdrop()
+  schedule()
+
+  return {
+    get options() {
+      return { ...config }
+    },
+
+    update(next = {}) {
+      config = { ...config, ...next }
+      applyBackdrop()
+      schedule()
+    },
+
+    refresh: schedule,
+
+    destroy() {
+      if (destroyed) return
+      destroyed = true
+      if (frame) cancelAnimationFrame(frame)
+      observer?.disconnect()
+      filter?.destroy()
+      element.classList.remove('liquid-glass')
+      element.style.removeProperty('--lg-backdrop')
+      element.style.removeProperty('--lg-radius')
+      element.style.removeProperty('--lg-specular')
+    },
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { createLiquidGlass, defaultOptions } from './glass.js'
+export { createDisplacementMap } from './displacement.js'
+export { injectStyles } from './styles.js'

package/src/styles.js

@@ -0,0 +1,35 @@
+const STYLE_ID = 'mizuui-liquid-glass-core-styles'
+
+const CSS = `
+.liquid-glass {
+  position: relative;
+  isolation: isolate;
+  border-radius: var(--lg-radius, 24px);
+  -webkit-backdrop-filter: var(--lg-backdrop, none);
+  backdrop-filter: var(--lg-backdrop, none);
+  transform: translateZ(0);
+}
+
+.liquid-glass::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  border-radius: inherit;
+  pointer-events: none;
+  box-shadow:
+    inset 2px 2px 1px -2px rgba(255, 255, 255, calc(0.9 * var(--lg-specular, 1))),
+    inset -1.5px -1.5px 1px -1.5px rgba(255, 255, 255, calc(0.6 * var(--lg-specular, 1))),
+    inset 0 0 6px 1px rgba(255, 255, 255, calc(0.25 * var(--lg-specular, 1)));
+}
+`
+
+export function injectStyles() {
+  if (typeof document === 'undefined') return
+  if (document.getElementById(STYLE_ID)) return
+
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = CSS
+  document.head.appendChild(style)
+}