@tsogtoodev/shingen-metal 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -33,7 +33,7 @@ declare type __VLS_WithTemplateSlots<T, S> = T & {
     };
 };
 
-export declare function createInstance(opts: CreateInstanceOptions): MetalFxInstance;
+export declare function createInstance(opts: CreateInstanceOptions): ShingenMetalInstance;
 
 declare interface CreateInstanceOptions {
     hostCanvas: HTMLCanvasElement;
@@ -50,12 +50,45 @@ declare interface CreateInstanceOptions {
     onFirstCopy?: () => void;
 }
 
-export declare function destroyInstance(inst: MetalFxInstance): void;
+export declare function destroyInstance(inst: ShingenMetalInstance): void;
 
-/** Converts `#rrggbb` (or `#rgb`) to a normalized `[r, g, b]` triple (0–1). */
 export declare function hexToRgb(hex: string): [number, number, number];
 
-export declare const MetalFx: __VLS_WithTemplateSlots<DefineComponent<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<MetalFxProps>, {
+export declare function pauseShared(): void;
+
+export declare interface Preset {
+    name: PresetName;
+    modes: Record<PresetTheme, PresetMode>;
+}
+
+export declare interface PresetMode {
+    colors: [string, string, string, string, string, string, string];
+    alphas: [number, number, number, number, number, number, number];
+    direction: number;
+    speed: number;
+    intensity: number;
+    scale: number;
+    softness: number;
+    distortion: number;
+    complexity: number;
+    shape: number;
+    blur: number;
+    vignette: number;
+    vigOpacity: number;
+    shaderOpacity: number;
+}
+
+export declare type PresetName = 'chromatic' | 'silver' | 'gold';
+
+export declare const PRESETS: Record<PresetName, Preset>;
+
+export declare type PresetTheme = 'dark' | 'light';
+
+export declare function resumeShared(): void;
+
+export declare function setSharedPreset(name: PresetName, theme: PresetTheme): void;
+
+export declare const ShingenMetal: __VLS_WithTemplateSlots<DefineComponent<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<ShingenMetalProps>, {
 variant: string;
 preset: string;
 theme: string;
@@ -65,9 +98,8 @@ normalizeHostStyles: boolean;
 disableGlow: boolean;
 scale: number;
 }>>, {
-/** The wrapper element, mirroring the React version's forwarded ref. */
 rootEl: Ref<HTMLDivElement | null, HTMLDivElement | null>;
-}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<MetalFxProps>, {
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<ShingenMetalProps>, {
 variant: string;
 preset: string;
 theme: string;
@@ -77,11 +109,11 @@ normalizeHostStyles: boolean;
 disableGlow: boolean;
 scale: number;
 }>>> & Readonly<{}>, {
-preset: MetalFxPreset;
+preset: ShingenMetalPreset;
 paused: boolean;
 scale: number;
-variant: MetalFxVariant;
-theme: MetalFxTheme;
+variant: ShingenMetalVariant;
+theme: ShingenMetalTheme;
 strength: number;
 normalizeHostStyles: boolean;
 disableGlow: boolean;
@@ -89,7 +121,7 @@ disableGlow: boolean;
     default?(_: {}): any;
 }>;
 
-export declare interface MetalFxInstance {
+export declare interface ShingenMetalInstance {
     canvas: HTMLCanvasElement;
     ctx: CanvasRenderingContext2D;
     cssWidth: number;
@@ -100,222 +132,37 @@ export declare interface MetalFxInstance {
     shaderScale: number;
     opacityMul: number;
     visible: boolean;
-    /** Per-instance freeze flag. When true the instance's 2D canvas keeps the
-     *  last copied frame; the shared GL loop continues for any other unpaused
-     *  instance. */
     paused: boolean;
-    /** Set to true after the first successful copyShaderToInstance — so an
-     *  instance that mounts already paused still gets one frame painted before
-     *  it freezes (otherwise it would render a blank canvas). */
     everCopied: boolean;
     dpr: number;
-    /** Master scale multiplier for absolute-pixel internals (glow stroke
-     *  widths/blurs, reflection stroke band, etc.). 1 is the baseline. Set to
-     *  2 for a CSS-zoomed 2× hero so glow + reflection grow with the layout. */
     scale: number;
     onAfterFrame?: () => void;
-    /** One-shot callback fired after the very first copyShaderToInstance.
-     *  Auto-cleared by the loop so it never fires twice. */
     onFirstCopy?: () => void;
 }
 
-/**
- * Bundled preset names. Each preset ships both a dark and light mode block.
- */
-export declare type MetalFxPreset = 'chromatic' | 'silver' | 'gold';
+export declare type ShingenMetalPreset = 'chromatic' | 'silver' | 'gold';
 
-/**
- * Props for the MetalFx Vue component. The single host element to wrap is
- * passed as the default slot (button, anchor, div, ...). MetalFx measures it
- * via `ResizeObserver` and paints its canvas + glow on top. Extra attributes
- * (class, style, event listeners, ...) fall through to the wrapper element.
- */
-export declare interface MetalFxProps {
-    /**
-     * Variant — controls the shader sampling scale + ring width.
-     * - `button` (default): pill-style ring at 1 px wide, scale 1.6
-     * - `circle`: compact circle with a 2 px ring, scale 1.3
-     */
-    variant?: MetalFxVariant;
-    /**
-     * Color preset. All three presets ship both dark and light mode tunings —
-     * `theme` picks the right side at runtime.
-     * @default 'chromatic'
-     */
-    preset?: MetalFxPreset;
-    /**
-     * Theme mode. `'auto'` (default) resolves via
-     * `matchMedia('(prefers-color-scheme: dark)')` and switches live when the
-     * OS theme changes. Pass `'dark'` or `'light'` to pin a specific mode.
-     * @default 'auto'
-     */
-    theme?: MetalFxTheme;
-    /**
-     * Effect strength (0..1). Multiplies the shader bitmap opacity and the glow
-     * SVG alpha. The shader continues to animate at full intensity at any value;
-     * only the rendered alpha onto the host is scaled. Lighter values let the
-     * underlying child surface show through more strongly.
-     * @default 1
-     */
+export declare interface ShingenMetalProps {
+    variant?: ShingenMetalVariant;
+    preset?: ShingenMetalPreset;
+    theme?: ShingenMetalTheme;
     strength?: number;
-    /**
-     * Pause the shader animation. The visible canvas keeps the last painted
-     * frame so the metal silhouette stays on screen.
-     * @default false
-     */
     paused?: boolean;
-    /**
-     * Optional explicit border radius (CSS px). When omitted, MetalFx reads the
-     * computed border-radius of the wrapped child each resize.
-     */
     borderRadius?: number;
-    /**
-     * When true, MetalFx normalizes the host element's outer chrome (border /
-     * outline / box-shadow) so user-provided component styles don't clash with
-     * the metal ring. Inner fills, typography, and content remain untouched.
-     * @default true
-     */
     normalizeHostStyles?: boolean;
-    /**
-     * Neighbour elements that should receive a soft proximity reflection of the
-     * metal effect. Reflections only render when the resolved theme is `dark` —
-     * pass-through in light mode (no DOM scan, no per-frame work).
-     *
-     * Pass template refs to the sibling DOM elements you want to receive the
-     * reflection (chips next to a send button, search field next to an Upgrade
-     * pill, ...).
-     */
-    reflectionTargets?: ReadonlyArray<MetalFxReflectionTarget>;
-    /**
-     * Disable the wandering halo overlay. The shader ring still renders.
-     * @default false
-     */
+    reflectionTargets?: ReadonlyArray<ShingenMetalReflectionTarget>;
     disableGlow?: boolean;
-    /**
-     * Override the shader sampling scale. Larger values zoom into the shared
-     * shader (visibly bigger pattern features); smaller values zoom out.
-     * Defaults to the variant's baseline (1.6 for `'button'`, 1.3 for
-     * `'circle'`) multiplied by `scale`.
-     */
     shaderScale?: number;
-    /**
-     * Override the ring thickness in CSS pixels. Defaults to the variant's
-     * baseline (1 for `'button'`, 2 for `'circle'`) multiplied by `scale`.
-     */
     ringCssPx?: number;
-    /**
-     * Master scale multiplier for every absolute-pixel constant the engine
-     * uses internally. Set this when you render the wrapped element at a
-     * non-1× size (e.g. inside a CSS `zoom: 2` container, or when you've
-     * doubled all your Tailwind sizes by hand). It scales:
-     *   - shader sampling (so pattern features grow proportionally)
-     *   - ring thickness on the canvas
-     *   - glow SVG stroke widths, blur radii, fade-circle radius, and the
-     *     small inset/outward offsets that position the catch-light
-     *   - reflection canvas stroke band, border-highlight thickness, and the
-     *     reference draw width baseline
-     * @default 1
-     */
     scale?: number;
 }
 
-/**
- * A reflection target: a Vue template ref holding the sibling DOM element
- * (or `null` before mount), or the element itself.
- */
-export declare type MetalFxReflectionTarget = Ref<HTMLElement | null> | HTMLElement | null;
+export declare type ShingenMetalReflectionTarget = Ref<HTMLElement | null> | HTMLElement | null;
 
-/**
- * Theme mode for the metal effect.
- *
- * - `auto` (default): follows the user's `prefers-color-scheme` and updates
- *   live when the OS / browser theme changes (also gracefully falls back to
- *   `dark` during SSR or when `matchMedia` is unavailable).
- * - `dark`: pin to the dark-mode tunings regardless of system preference.
- * - `light`: pin to the light-mode tunings regardless of system preference.
- *
- * Drive this from your app's theme state if you have a manual toggle that
- * doesn't follow the OS — otherwise `auto` is the right default.
- */
-export declare type MetalFxTheme = 'dark' | 'light' | 'auto';
+export declare type ShingenMetalTheme = 'dark' | 'light' | 'auto';
 
-/**
- * Variant for the metal effect.
- * - 'button' (default): pill-shaped 134×40 baseline with shaderScale 1.6
- * - 'circle': compact 32×32 circle baseline with shaderScale 1.3
- *
- * In practice the wrapped child's measured dimensions drive the visible size —
- * the variant only controls the shader sampling scale and ring thickness.
- */
-export declare type MetalFxVariant = 'button' | 'circle';
-
-export declare function pauseShared(): void;
-
-export declare interface Preset {
-    name: PresetName;
-    modes: Record<PresetTheme, PresetMode>;
-}
-
-export declare interface PresetMode {
-    /** 7-stop palette, indexed against `u_color1..u_color7`. */
-    colors: [string, string, string, string, string, string, string];
-    /** Per-stop alpha weights (0..1). */
-    alphas: [number, number, number, number, number, number, number];
-    /** Drift angle (degrees). Multiplied by π/180 before upload. */
-    direction: number;
-    /** Time multiplier applied JS-side before passing into the shader. */
-    speed: number;
-    /** Plasma intensity (wave-field amplitude). */
-    intensity: number;
-    /** Noise zoom — smaller = chunkier features. */
-    scale: number;
-    /** Edge softness (effect 1 ignores; carried for parity). */
-    softness: number;
-    /** Warp strength on the field (0..1). */
-    distortion: number;
-    /** FBM octave / frequency multiplier. */
-    complexity: number;
-    /** Reserved (effect 1 ignores). */
-    shape: number;
-    /** 9-tap blur sample radius (0 = single tap). */
-    blur: number;
-    /** Vignette range (0..1). */
-    vignette: number;
-    /** Vignette darkening strength (0..1). */
-    vigOpacity: number;
-    /** Final alpha multiplier in the fragment shader (0..1). */
-    shaderOpacity: number;
-}
-
-/**
- * Bundled preset configurations for the metal effect.
- *
- * Direct ports of the three JSON files shipped alongside the canonical demo:
- *   • preset-chromatic-both-modes.json
- *   • preset-silver-both-modes.json
- *   • preset-gold-both-modes.json
- *
- * Each preset carries a `dark` and `light` mode block. Values are reproduced
- * byte-for-byte (including the `chromatic.dark.scale = 1.6` quirk that gives
- * the dark chromatic preset its noticeably chunkier features compared with
- * the other dark-mode entries).
- *
- * The fragment shader only consumes uniforms 1..5 of `palette`/`alphas` for
- * the Plasma effect, but the JSON ships 7 colors / alphas to stay
- * forward-compatible with effect 24 (Noise Flow Wide). We keep the full 7 so
- * a future variant could opt into other effects without re-importing the
- * preset definitions.
- */
-export declare type PresetName = 'chromatic' | 'silver' | 'gold';
-
-export declare const PRESETS: Record<PresetName, Preset>;
-
-export declare type PresetTheme = 'dark' | 'light';
-
-export declare function resumeShared(): void;
-
-export declare function setSharedPreset(name: PresetName, theme: PresetTheme): void;
+export declare type ShingenMetalVariant = 'button' | 'circle';
 
-export declare function updateInstance(inst: MetalFxInstance, patch: Partial<Pick<MetalFxInstance, 'cssWidth' | 'cssHeight' | 'cornerRadius' | 'kind' | 'shaderScale' | 'ringCssPx' | 'opacityMul' | 'paused' | 'scale'>>): void;
+export declare function updateInstance(inst: ShingenMetalInstance, patch: Partial<Pick<ShingenMetalInstance, 'cssWidth' | 'cssHeight' | 'cornerRadius' | 'kind' | 'shaderScale' | 'ringCssPx' | 'opacityMul' | 'paused' | 'scale'>>): void;
 
 export { }