@tsogtoodev/shingen-metal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Antalik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# shingen-metal
+
+Animated WebGL "liquid metal" effect for Vue 3 — a port of [metal-fx](https://github.com/Jakubantalik/metal-fx) (React) by Jakub Antalik. Wrap a button, chip, or icon and it gets a real-time metal ring with optional proximity reflection on neighbouring elements.
+
+## Install
+
+```bash
+npm install shingen-metal
+```
+
+## Quick start
+
+```vue
+<script setup>
+import { MetalFx } from 'shingen-metal';
+</script>
+
+<template>
+  <MetalFx variant="button">
+    <button class="upgrade-pill">Upgrade to Pro</button>
+  </MetalFx>
+</template>
+```
+
+The component wraps a single slotted host element, measures it, and paints an animated metal ring on top. The child stays fully interactive — overlays sit above it with `pointer-events: none`.
+
+## Variants
+
+```vue
+<MetalFx variant="button">  <!-- Pill silhouette, 1 px ring, scale 1.6 -->
+  <button>Upgrade to Pro</button>
+</MetalFx>
+
+<MetalFx variant="circle">  <!-- Compact circle, 2 px ring, scale 1.3 -->
+  <button>↑</button>
+</MetalFx>
+```
+
+## Presets
+
+Three bundled palettes, each with a tuned dark and light mode block:
+
+```vue
+<MetalFx preset="chromatic" />  <!-- Iridescent rainbow (default) -->
+<MetalFx preset="silver" />     <!-- Cool steel -->
+<MetalFx preset="gold" />       <!-- Warm gold -->
+```
+
+## Theme
+
+```vue
+<MetalFx theme="auto" />    <!-- Follows prefers-color-scheme (default) -->
+<MetalFx theme="dark" />    <!-- Pin to dark backgrounds -->
+<MetalFx theme="light" />   <!-- Pin to light backgrounds -->
+```
+
+`auto` reads the OS / browser theme on mount and subscribes to live changes via `matchMedia('(prefers-color-scheme: dark)')`, so the metal frame switches over instantly when the user toggles their system theme. SSR-safe — the initial render falls back to `dark` and rehydrates to the resolved theme on the client.
+
+If your app has its own theme toggle that doesn't follow the OS, drive `theme` from your app state instead:
+
+```vue
+<MetalFx :theme="appTheme">...</MetalFx>
+```
+
+## Strength
+
+```vue
+<MetalFx :strength="0.7">  <!-- 70% effect intensity -->
+  <button>Upgrade to Pro</button>
+</MetalFx>
+```
+
+`strength` runs from `0` (invisible) to `1` (full, default). It scales the canvas and glow opacity without changing the underlying shader animation.
+
+## Paused
+
+```vue
+<MetalFx paused>
+  <button>Upgrade to Pro</button>
+</MetalFx>
+```
+
+Freezes the shader on its current frame. The metal silhouette stays visible.
+
+## Proximity reflection (dark mode only)
+
+Pass template refs to neighbouring elements and they receive a soft, mirrored reflection of the metal ring:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { MetalFx } from 'shingen-metal';
+
+const chipRef = ref(null);
+</script>
+
+<template>
+  <button ref="chipRef">Tools</button>
+  <MetalFx variant="circle" :reflection-targets="[chipRef]">
+    <button aria-label="Send">↑</button>
+  </MetalFx>
+</template>
+```
+
+Reflections are skipped automatically when the resolved theme is `light` — no DOM scanning, no per-frame work in light mode.
+
+## Performance
+
+- One shared WebGL context is reused across every mounted `<MetalFx>` on the page. The shader is compiled once.
+- A single `requestAnimationFrame` loop drives every instance. Per-frame work for one mount: a `gl.drawArrays` plus N×`drawImage` copies (one per visible instance).
+- `IntersectionObserver` pauses per-instance copies when the host scrolls offscreen. When every instance is offscreen the GL render is skipped too.
+- `ResizeObserver` callbacks are debounced through RAF.
+- The GL context, program, and buffer are released when the last `<MetalFx>` unmounts.
+
+## Server-side rendering
+
+The component renders a transparent placeholder during SSR and only mounts the WebGL pipeline after hydration on the client. No flash of broken effect, no SSR errors.
+
+## Sizing
+
+`MetalFx` does not force any dimensions onto the wrapped child — the wrapper sizes itself to whatever the child renders. Style your child the way you normally would (intrinsic content, CSS class, or inline style):
+
+```vue
+<!-- Pattern 1 (recommended): size the child. -->
+<MetalFx variant="circle">
+  <button style="width: 36px; height: 36px" aria-label="Send">↑</button>
+</MetalFx>
+
+<MetalFx>
+  <button class="rounded-full px-6 h-10">Upgrade to Pro</button>
+</MetalFx>
+```
+
+If you want a metal frame larger than the child (e.g. padding around an icon), size the wrapper instead and explicitly stretch the child to fill:
+
+```vue
+<!-- Pattern 2: size the wrapper, child fills. -->
+<MetalFx style="width: 36px; height: 36px" variant="circle">
+  <button style="width: 100%; height: 100%" aria-label="Send">↑</button>
+</MetalFx>
+```
+
+Both patterns work; pick whichever fits your layout. The wrapper is `display: inline-flex` so it lays out inline like a button.
+
+## Custom border radius
+
+By default `MetalFx` reads the computed `border-radius` of the wrapped child each resize. Pass an explicit override when needed:
+
+```vue
+<MetalFx :border-radius="20">
+  <button>Upgrade to Pro</button>
+</MetalFx>
+```
+
+## Demo
+
+```bash
+npm install
+npm run dev
+```
+
+## License
+
+MIT — port of [metal-fx](https://github.com/Jakubantalik/metal-fx) © [Jakub Antalik](https://github.com/Jakubantalik). See [LICENSE](./LICENSE).