@tsogtoodev/shingen-metal 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,321 @@
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { DefineComponent } from 'vue';
+import { ExtractPropTypes } from 'vue';
+import { PropType } from 'vue';
+import { PublicProps } from 'vue';
+import { Ref } from 'vue';
+
+declare type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+
+declare type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: PropType<T[K]>;
+        required: true;
+    };
+};
+
+declare type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+
+declare type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+
+export declare function createInstance(opts: CreateInstanceOptions): MetalFxInstance;
+
+declare interface CreateInstanceOptions {
+    hostCanvas: HTMLCanvasElement;
+    cssWidth: number;
+    cssHeight: number;
+    cornerRadius: number;
+    kind: 'pill' | 'circle';
+    shaderScale?: number;
+    ringCssPx?: number;
+    opacityMul?: number;
+    paused?: boolean;
+    scale?: number;
+    onAfterFrame?: () => void;
+    onFirstCopy?: () => void;
+}
+
+export declare function destroyInstance(inst: MetalFxInstance): 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>, {
+variant: string;
+preset: string;
+theme: string;
+strength: number;
+paused: boolean;
+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>, {
+variant: string;
+preset: string;
+theme: string;
+strength: number;
+paused: boolean;
+normalizeHostStyles: boolean;
+disableGlow: boolean;
+scale: number;
+}>>> & Readonly<{}>, {
+preset: MetalFxPreset;
+paused: boolean;
+scale: number;
+variant: MetalFxVariant;
+theme: MetalFxTheme;
+strength: number;
+normalizeHostStyles: boolean;
+disableGlow: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>, {
+    default?(_: {}): any;
+}>;
+
+export declare interface MetalFxInstance {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    cssWidth: number;
+    cssHeight: number;
+    cornerRadius: number;
+    kind: 'pill' | 'circle';
+    ringCssPx: number;
+    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';
+
+/**
+ * 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
+     */
+    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
+     */
+    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;
+
+/**
+ * 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';
+
+/**
+ * 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 function updateInstance(inst: MetalFxInstance, patch: Partial<Pick<MetalFxInstance, 'cssWidth' | 'cssHeight' | 'cornerRadius' | 'kind' | 'shaderScale' | 'ringCssPx' | 'opacityMul' | 'paused' | 'scale'>>): void;
+
+export { }