argentui 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+import * as react from 'react';
+import { LiquidMetalParams } from '@paper-design/shaders-react';
+
+/**
+ * Argent's own liquid-metal shader — a clean-room WebGL2 implementation of the
+ * classic recipe: hard light→dark reflection banding, curvature-warped UVs,
+ * time-driven simplex-noise flow, per-channel chromatic dispersion, and a rim
+ * lift. No third-party shader code beyond the public-domain-style simplex
+ * noise (Ashima Arts / Stefan Gustavson, MIT).
+ *
+ * Used when a surface sets `engine="native"`; removes the need for
+ * @paper-design/shaders-react entirely.
+ */
+interface NativeMetalParams {
+    /** Highlight band colour (hex). */
+    light: string;
+    /** Shadow band colour (hex). */
+    dark: string;
+    /** Stripe density. */
+    repetition: number;
+    /** Band direction in degrees. */
+    angle: number;
+    /** Band edge softness 0–1. */
+    softness: number;
+    /** Per-channel band offset (chromatic dispersion). */
+    dispersion: number;
+    /** Noise warp amount. */
+    distortion: number;
+    /** Animation speed (0 = still). */
+    speed: number;
+    /** Pattern scale — higher spreads the bands out. */
+    scale: number;
+}
+type MetalEngine = "paper" | "native";
+declare const NATIVE_TONES: Record<string, Omit<NativeMetalParams, "speed" | "scale">>;
+interface MetalMount {
+    update(params: Partial<NativeMetalParams>): void;
+    destroy(): void;
+}
+/** Mount the native liquid-metal shader on a canvas. Returns null without WebGL2. */
+declare function mountMetal(canvas: HTMLCanvasElement, params: NativeMetalParams): MetalMount | null;
+
+/**
+ * The liquid-metal surface is Paper's `LiquidMetal` WebGL shader
+ * (@paper-design/shaders) run with `shape="none"` so it fills the whole element
+ * instead of painting a blob. Each tone is a tuned set of shader params; the
+ * canvas sits behind the content and is clipped to the surface's radius.
+ *
+ * `@paper-design/shaders-react` is a peer dependency — install it alongside
+ * `argentui`. It is licensed under PolyForm Shield by Paper.
+ */
+type MetalTone = "silver" | "gold" | "gunmetal" | "obsidian";
+type Tuned = Pick<LiquidMetalParams, "colorBack" | "colorTint" | "repetition" | "softness" | "shiftRed" | "shiftBlue" | "distortion" | "contour" | "angle">;
+declare const TONE_PARAMS: Record<MetalTone, Tuned>;
+/** True once mounted on the client — the WebGL canvas can't render during SSR. */
+declare function useMounted(): boolean;
+/** True when the user prefers reduced motion — the metal freezes (speed 0). */
+declare function useReducedMotion(): boolean;
+/**
+ * Reports whether `ref` is on/near screen. Each metal surface is a WebGL
+ * canvas, and browsers cap concurrent contexts (~16) — so we only mount the
+ * shader while it's visible and release the context when it scrolls away.
+ */
+declare function useInView(ref: React.RefObject<Element | null>, margin?: string): boolean;
+/**
+ * Finishes — shader presets tuned to the shape and size of the element. One
+ * pattern does not fit all: a card wants broad flowing bands, a thin progress
+ * bar wants many stripes crossing it, a 22px toggle thumb wants one soft
+ * highlight like a ball bearing, and a hairline badge rim wants dense bands so
+ * a tiny visible slice always catches some light.
+ */
+type MetalFinish = "surface" | "button" | "bar" | "orb" | "rim";
+interface FinishTuning {
+    /** Band direction override (deg). */
+    angle?: number;
+    /** Random per-mount angle variation (±deg) so identical elements don't look cloned. */
+    angleJitter?: number;
+    repetition?: number;
+    softness?: number;
+    distortion?: number;
+    /** Multiplier on the tone's chromatic shift. */
+    shift?: number;
+    /** Default pattern scale. */
+    scale?: number;
+    /** Multiplier on the animation speed. */
+    speed?: number;
+}
+declare const FINISHES: Record<MetalFinish, FinishTuning>;
+/**
+ * Effects — the character of the liquid's motion, independent of tone and
+ * finish: how soft the bands are, how hard the noise churns them, how fast
+ * everything moves.
+ */
+type MetalEffect = "flow" | "molten" | "ripple" | "chrome" | "wave";
+interface EffectTuning {
+    angle?: number;
+    repetition?: number;
+    softness?: number;
+    distortion?: number;
+    /** Multiplier on chromatic shift. */
+    shift?: number;
+    /** Multiplier on animation speed. */
+    speed?: number;
+}
+declare const EFFECTS: Record<MetalEffect, EffectTuning>;
+interface MetalFillProps {
+    tone: MetalTone;
+    /** Shader animation speed (0 pauses). */
+    speed?: number;
+    /** Pattern scale — higher spreads the bands out. Defaults per finish. */
+    scale?: number;
+    /** `"paper"` (Paper's LiquidMetal, default) or `"native"` (Argent's own shader). */
+    engine?: MetalEngine;
+    /** Shape-tuned shader preset. Defaults to `"surface"`. */
+    finish?: MetalFinish;
+    /** Motion character preset. Defaults to `"flow"`. */
+    effect?: MetalEffect;
+    /** Band direction in degrees — overrides the tone/finish default. */
+    angle?: number;
+}
+/** The shader canvas, absolutely filling its positioned parent (when in view). */
+declare function MetalFill({ tone, speed, scale, engine, finish, effect, angle }: MetalFillProps): react.JSX.Element;
+
+/** Where the liquid metal shows: just the edge, or the whole surface. */
+type MetalVariant = "border" | "fill";
+/** Border framing: a single rim, or a rim plus an inner hairline frame. */
+type MetalFrame = "single" | "double";
+interface MetalProps extends React.HTMLAttributes<HTMLElement> {
+    /** Element/component to render. Defaults to `div`. */
+    as?: React.ElementType;
+    /** Metal finish. */
+    tone?: MetalTone;
+    /** `"border"` (metal edge only, default) or `"fill"` (metal fills the surface). */
+    variant?: MetalVariant;
+    /** `"single"` rim (default) or `"double"` — rim plus an inner hairline frame. */
+    frame?: MetalFrame;
+    /** Let the metal show faintly through the interior panel (border variant). */
+    tint?: boolean;
+    /** Border thickness in px (border variant). */
+    borderWidth?: number;
+    /** Fill the whole surface with metal on hover (border variant). */
+    revealOnHover?: boolean;
+    /** Corner radius in px. */
+    radius?: number;
+    /** Shader animation speed (0 pauses the metal). */
+    speed?: number;
+    /** Pattern scale — higher spreads the reflection bands out. */
+    metalScale?: number;
+    /** Shader engine: Paper's LiquidMetal (default) or Argent's own. */
+    engine?: MetalEngine;
+    /** Shape-tuned shader preset. Defaults to `"surface"`. */
+    finish?: MetalFinish;
+    /** Motion character: flow, molten, ripple, chrome, or wave. */
+    effect?: MetalEffect;
+    /** Band direction in degrees — overrides the tone/finish default. */
+    angle?: number;
+    /** A specular streak that sweeps across on hover. */
+    sheen?: boolean;
+    /**
+     * A frosted standoff ring outside the metal — a few px of backdrop blur
+     * finished with a ~5% hairline. `true` for 8px, or a number for the ring
+     * width. Theme the line with `--argent-halo-line`.
+     */
+    halo?: boolean | number;
+}
+/**
+ * A liquid-metal surface powered by Paper's `LiquidMetal` shader. By default the
+ * metal is just the edge; pass `variant="fill"` for a full metal surface, or
+ * `revealOnHover` to fill in on interaction. The base for every Argent component.
+ */
+declare const Metal: react.ForwardRefExoticComponent<MetalProps & react.RefAttributes<HTMLElement>>;
+interface MetalCardProps extends MetalProps {
+}
+/** A padded liquid-metal container. Metal edge by default. */
+declare const MetalCard: react.ForwardRefExoticComponent<MetalCardProps & react.RefAttributes<HTMLElement>>;
+interface MetalButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    tone?: MetalTone;
+    size?: "sm" | "md" | "lg";
+    /** `"border"` (default — readable, fills on hover) or `"fill"` (full chrome). */
+    variant?: MetalVariant;
+    /** Corner radius in px. */
+    radius?: number;
+    borderWidth?: number;
+    /** Fill with metal on hover (border variant). Defaults to `true`. */
+    revealOnHover?: boolean;
+    /** Vibrate on press where supported. Defaults to `true`. */
+    haptics?: boolean;
+    speed?: number;
+    engine?: MetalEngine;
+    finish?: MetalFinish;
+    effect?: MetalEffect;
+    angle?: number;
+    halo?: boolean | number;
+}
+/** A liquid-metal button — readable at rest, molten on hover, with a stamped press. */
+declare const MetalButton: react.ForwardRefExoticComponent<MetalButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface MetalToggleProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
+    tone?: MetalTone;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    /** Vibrate on toggle where supported. Defaults to `true`. */
+    haptics?: boolean;
+}
+/**
+ * A mercury switch — the thumb is a drop of liquid metal that slides (and
+ * squishes) across a dark channel.
+ */
+declare const MetalToggle: react.ForwardRefExoticComponent<MetalToggleProps & react.RefAttributes<HTMLButtonElement>>;
+interface MetalProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+    tone?: MetalTone;
+    /** 0–100. Omit for an indeterminate molten sweep. */
+    value?: number;
+    /** Track height in px. */
+    height?: number;
+}
+/** A molten progress bar — liquid metal rising in a dark channel. */
+declare const MetalProgress: react.ForwardRefExoticComponent<MetalProgressProps & react.RefAttributes<HTMLDivElement>>;
+interface MetalBadgeProps extends Omit<MetalProps, "as" | "variant"> {
+}
+/** A small liquid-metal pill — a metal rim around a quiet label. */
+declare const MetalBadge: react.ForwardRefExoticComponent<MetalBadgeProps & react.RefAttributes<HTMLElement>>;
+
+/** Where the metal lives in shader text: the whole glyph, or just its edge. */
+type MetalTextVariant = "fill" | "outline";
+interface MetalTextProps extends React.HTMLAttributes<HTMLElement> {
+    /** Element to render. Defaults to `span`. */
+    as?: React.ElementType;
+    tone?: MetalTone;
+    /** Animate the highlight band across the glyphs (CSS mode). Defaults to `true`. */
+    shimmer?: boolean;
+    /**
+     * Pour the real liquid-metal shader into the glyphs — flowing bands, liquid
+     * edges, chromatic fringe. Costs a WebGL canvas; the CSS gradient renders as
+     * a placeholder until the shader is ready, and stands in wherever WebGL
+     * isn't. Children must be a plain string in this mode.
+     */
+    shader?: boolean;
+    /**
+     * Shader mode: `"fill"` (metal fills the glyphs, default) or `"outline"` —
+     * the metal runs around the edge of each letterform and the interior takes
+     * `fill` / `fillGradient`.
+     */
+    variant?: MetalTextVariant;
+    /** Interior colour for `variant="outline"`. */
+    fill?: string;
+    /** Interior vertical gradient `[top, bottom]` for `variant="outline"` — wins over `fill`. */
+    fillGradient?: [string, string];
+    /** Metal edge thickness in px for `variant="outline"`. Defaults to ~5% of the font size. */
+    outlineWidth?: number;
+    /** Type size in px (shader mode). Defaults to `64`. */
+    fontSize?: number;
+    /** Weight for the glyph silhouette (shader mode). Defaults to `800`. */
+    fontWeight?: number;
+    /**
+     * Font for the silhouette (shader mode). Rendered inside an SVG image, which
+     * sees system fonts only — to use a webfont, pass `fontCss` with a
+     * data-URI @font-face for the same family.
+     */
+    fontFamily?: string;
+    /**
+     * Raw CSS embedded in the glyph SVG (shader mode) — typically a @font-face
+     * whose `src` is a data: URI, which lets webfonts (e.g. Google Fonts) render
+     * inside the silhouette. Load the same face into `document.fonts` so the
+     * width measurement matches.
+     */
+    fontCss?: string;
+    /** Shader animation speed (0 pauses). */
+    speed?: number;
+}
+/**
+ * Metal type. By default a chrome gradient clipped to the glyphs with a flowing
+ * shimmer — pure CSS, use it freely at any scale. Pass `shader` to pour the
+ * real liquid-metal shader into the letterforms — `variant="fill"` floods the
+ * glyphs; `variant="outline"` runs the metal around their edges over a dark or
+ * gradient interior.
+ */
+declare const MetalText: react.ForwardRefExoticComponent<MetalTextProps & react.RefAttributes<HTMLElement>>;
+
+interface MetalLogoProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Image URL (or data URI) with a transparent background — the metal flows inside its silhouette. */
+    src: string;
+    tone?: MetalTone;
+    /** Rendered size in px (square by default). */
+    size?: number;
+    width?: number;
+    height?: number;
+    /** Shader animation speed (0 pauses). */
+    speed?: number;
+}
+/**
+ * Liquid metal poured into a logo — pass any image with a transparent
+ * background and the metal flows inside its silhouette. The classic
+ * liquid-metal treatment for marks, monograms, and icons.
+ */
+declare function MetalLogo({ src, tone, size, width, height, speed, style, ...rest }: MetalLogoProps): react.JSX.Element;
+
+/**
+ * Tiny haptics for metal presses — `navigator.vibrate` where available
+ * (Android Chrome; iOS Safari ignores it). On by default, like Glacé.
+ */
+/** Globally enable/disable Argent haptics. */
+declare function setHaptics(on: boolean): void;
+
+export { EFFECTS, FINISHES, Metal, MetalBadge, type MetalBadgeProps, MetalButton, type MetalButtonProps, MetalCard, type MetalCardProps, type MetalEffect, type MetalEngine, MetalFill, type MetalFillProps, type MetalFinish, type MetalFrame, MetalLogo, type MetalLogoProps, type MetalMount, MetalProgress, type MetalProgressProps, type MetalProps, MetalText, type MetalTextProps, type MetalTextVariant, MetalToggle, type MetalToggleProps, type MetalTone, type MetalVariant, NATIVE_TONES, type NativeMetalParams, TONE_PARAMS, mountMetal, setHaptics, useInView, useMounted, useReducedMotion };