@kongyo2/cards-css 0.2.0 → 0.3.0

package/dist-types/types.d.ts

@@ -58,6 +58,88 @@ export interface ShowcaseOptions {
     /** Spring tuning while the showcase runs. */
     spring?: SpringTuning;
 }
+/** Built-in foil colour schemes for {@link PaletteOptions.preset}. */
+export type PalettePreset = "rainbow" | "gold" | "aurora" | "ruby" | "sapphire" | "mono";
+/**
+ * Foil colour-palette / theming. Every field maps onto the foil CSS custom
+ * properties, so a palette can be supplied up front or swapped at runtime with
+ * `card.setPalette(...)`. Colours accept any CSS colour string.
+ */
+export interface PaletteOptions {
+    /** A built-in scheme used as the base; the explicit fields below override it. */
+    preset?: PalettePreset;
+    /** Holographic spectrum stops (`--sunpillar-1…6`). 1–6 colours; fewer are cycled to fill the ramp. */
+    sunpillars?: string[];
+    /** Rainbow stops for the `holo` foil sweep (`--red` / `--yellow` / `--green` / `--blue` / `--violet`). 1–5 colours, cycled. */
+    spectrum?: string[];
+    /** Ramp stops for the `cosmos` foil (`--cosmos-clr-1…6`). 1–6 colours, cycled. */
+    cosmos?: string[];
+    /** Card edge highlight colour (`--card-edge`). */
+    edge?: string;
+    /** Card back fill colour (`--card-back`). */
+    back?: string;
+    /** Card glow colour (`--card-glow`); equivalent to the top-level `glow` option. */
+    glow?: string;
+}
+/**
+ * Custom dynamic glare (reflected light). Supply a full `image` for total
+ * control, or compose the built-in pointer-tracking radial gradient from
+ * `shape` / `extent` / `size` / `stops`. Applies across every effect and can be
+ * updated at runtime with `card.setGlare(...)`.
+ */
+export interface GlareOptions {
+    /**
+     * Full `background-image` for the glare layer, overriding the built-in
+     * gradient on every effect. `var(--pointer-x)` / `var(--pointer-y)` are
+     * available for pointer tracking.
+     */
+    image?: string;
+    /** Radial-gradient shape when composing the gradient (default `circle`). */
+    shape?: "circle" | "ellipse";
+    /** Radial-gradient extent keyword, e.g. `farthest-corner` / `closest-side` (default `farthest-corner`). */
+    extent?: string;
+    /** Explicit gradient size — two values imply an ellipse (e.g. `60% 40%`), a single value a circle radius (e.g. `120px`); overrides `extent` when set. */
+    size?: string;
+    /** Colour stops, e.g. `["hsla(0,0%,100%,.8) 10%", "hsla(0,0%,0%,.5) 90%"]`. */
+    stops?: string[];
+    /** `mix-blend-mode` for the glare layer. */
+    blend?: string;
+    /** Glare opacity multiplier (mirrors `visual.glareOpacity`). */
+    opacity?: number;
+}
+/**
+ * Physical-behaviour tuning for the device-orientation (gyroscope) response.
+ * Passing `true` keeps the defaults; `false` disables gyroscope tilt.
+ */
+export interface GyroscopeOptions {
+    /** Master switch (default true); `false` matches `gyroscope: false`. */
+    enabled?: boolean;
+    /** Device tilt (deg) on the X axis (gamma) that reaches the full effect (default 16). Lower is more sensitive. */
+    rangeX?: number;
+    /** Device tilt (deg) on the Y axis (beta) that reaches the full effect (default 18). */
+    rangeY?: number;
+    /** Sensitivity multiplier applied to the raw tilt before clamping (default 1). */
+    sensitivity?: number;
+    /** Flip the horizontal response. */
+    invertX?: boolean;
+    /** Flip the vertical response. */
+    invertY?: boolean;
+}
+/**
+ * Foil 3D depth / extrusion simulation. Lifts the foil stack above the artwork
+ * in true 3D so it parallaxes as the card tilts, with a tilt-reactive contact
+ * shadow. Passing `true` enables it with the defaults.
+ */
+export interface DepthOptions {
+    /** Foil extrusion height in px — how far the foil floats above the artwork (default 14). */
+    strength?: number;
+    /** Perspective in px for the card's 3D space; lower exaggerates the depth (default 600). */
+    perspective?: number;
+    /** Contact-shadow opacity beneath the lifted card, 0–1 (default 0.35). */
+    shadow?: number;
+    /** Multiplier turning each extra layer's `parallax` into Z-lift, so stacked layers extrude in depth (default 1). */
+    layerScale?: number;
+}
 /** Fine-grained visual / effect control. Numeric fields are multipliers (1 = unchanged). */
 export interface VisualOptions {
     /** Foil brightness multiplier. */
@@ -123,13 +205,20 @@ export interface HoloCardOptions {
     effect?: HoloEffect;
     interactive?: boolean;
     activateOnClick?: boolean;
-    gyroscope?: boolean;
+    /** Device-orientation tilt: `true`/`false`, or an object for physical-behaviour tuning. */
+    gyroscope?: boolean | GyroscopeOptions;
     showcase?: boolean | ShowcaseOptions;
     glow?: string;
     aspectRatio?: number;
     textureSeed?: number;
     mask?: string | MaskOptions;
     foil?: string;
+    /** Foil colour palette / theming. */
+    palette?: PaletteOptions;
+    /** Custom dynamic glare (reflected light). */
+    glare?: GlareOptions;
+    /** Foil 3D depth / extrusion: `true` for the defaults, or an object to tune it. */
+    depth?: boolean | DepthOptions;
     /** Interaction & physics adjustments. */
     physics?: PhysicsOptions;
     /** Fine-grained visual control. */

package/dist-types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kongyo2/cards-css",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic holographic trading-card effect (tilt, shine, glare, holo / reverse / cosmos / glitter) with procedurally code-generated textures.",
   "type": "module",
   "license": "MIT",

package/src/dom.ts

@@ -19,6 +19,8 @@ export const CLASS = {
   loading: "holo-card--loading",
   masked: "holo-card--masked",
   maskCard: "holo-card--mask-card",
+  depth: "holo-card--depth",
+  customGlare: "holo-card--custom-glare",
   overlayInteractive: "holo-card__overlay--interactive",
 } as const;
 
@@ -39,6 +41,10 @@ export const applyVars = (element: HTMLElement, vars: CssVars | undefined): void
   }
 };
 
+const CSS_STRING_UNSAFE = /[\\"\n\r\f]/g;
+
+export const cssUrl = (value: string): string => `url("${value.replace(CSS_STRING_UNSAFE, (char) => `\\${char}`)}")`;
+
 export interface ResolvedMask {
   image: string | undefined;
   size: string | undefined;
@@ -91,11 +97,11 @@ export const buildLayerElement = (doc: Document, layer: HoloLayerOptions): HTMLE
     el.style.setProperty("--layer-parallax", String(layer.parallax));
   }
   if (layer.mask) {
-    el.style.setProperty("--layer-mask", `url(${layer.mask})`);
+    el.style.setProperty("--layer-mask", cssUrl(layer.mask));
     el.classList.add(`${CLASS.layer}--masked`);
   }
   if (layer.image) {
-    el.style.setProperty("--layer-image", `url(${layer.image})`);
+    el.style.setProperty("--layer-image", cssUrl(layer.image));
     el.style.setProperty("--layer-size", layer.size ?? "cover");
     el.style.setProperty("--layer-position", layer.position ?? "center");
   }

package/src/holo-card.ts

@@ -1,10 +1,21 @@
 import { adjust, clamp, round } from "./math.js";
 import { Spring, type SpringSetOpts, type SpringOpts, type SpringDynamics } from "./spring.js";
-import { CLASS, applyVars, buildLayerElement, normalizeMask } from "./dom.js";
+import { CLASS, applyVars, buildLayerElement, cssUrl, normalizeMask } from "./dom.js";
 import { getActiveCard, setActiveCard, subscribeActiveCard } from "./active-registry.js";
 import { resetBaseOrientation, subscribeOrientation, type RelativeOrientation } from "./orientation.js";
 import { generateTextures, texturesToCssVariables } from "./textures.js";
-import type { CssVars, HoloCardOptions, HoloLayerOptions, ShowcaseOptions, VisualOptions } from "./types.js";
+import { paletteToCssVariables, PALETTE_VARIABLES } from "./palette.js";
+import type {
+  CssVars,
+  DepthOptions,
+  GlareOptions,
+  GyroscopeOptions,
+  HoloCardOptions,
+  HoloLayerOptions,
+  PaletteOptions,
+  ShowcaseOptions,
+  VisualOptions,
+} from "./types.js";
 
 const requestFrame = (cb: () => void): number =>
   typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame(cb) : setTimeout(cb, 16);
@@ -102,6 +113,73 @@ const resolveShowcase = (showcase: boolean | ShowcaseOptions | undefined): Resol
   };
 };
 
+interface ResolvedGyroscope {
+  enabled: boolean;
+  rangeX: number;
+  rangeY: number;
+  sensitivity: number;
+  invertX: boolean;
+  invertY: boolean;
+}
+
+const DEFAULT_GYRO_RANGE_X = 16;
+const DEFAULT_GYRO_RANGE_Y = 18;
+
+const resolveGyroscope = (gyroscope: boolean | GyroscopeOptions | undefined): ResolvedGyroscope => {
+  const opts: GyroscopeOptions = gyroscope && typeof gyroscope === "object" ? gyroscope : {};
+  const enabled = typeof gyroscope === "boolean" ? gyroscope : (opts.enabled ?? true);
+  return {
+    enabled,
+    rangeX: opts.rangeX ?? DEFAULT_GYRO_RANGE_X,
+    rangeY: opts.rangeY ?? DEFAULT_GYRO_RANGE_Y,
+    sensitivity: opts.sensitivity ?? 1,
+    invertX: opts.invertX ?? false,
+    invertY: opts.invertY ?? false,
+  };
+};
+
+interface ResolvedDepth {
+  enabled: boolean;
+  strength: number;
+  perspective: number;
+  shadow: number;
+  layerScale: number;
+}
+
+const resolveDepth = (depth: boolean | DepthOptions | undefined): ResolvedDepth => {
+  const opts: DepthOptions = depth && typeof depth === "object" ? depth : {};
+  return {
+    enabled: Boolean(depth),
+    strength: opts.strength ?? 14,
+    perspective: opts.perspective ?? 600,
+    shadow: opts.shadow ?? 0.35,
+    layerScale: opts.layerScale ?? 1,
+  };
+};
+
+const DEFAULT_GLARE_STOPS = ["hsla(0, 0%, 100%, 0.8) 10%", "hsla(0, 0%, 100%, 0.65) 20%", "hsla(0, 0%, 0%, 0.5) 90%"];
+
+const composeGlareImage = (glare: GlareOptions): string | undefined => {
+  if (glare.image) {
+    return glare.image;
+  }
+  if (
+    glare.shape === undefined &&
+    glare.extent === undefined &&
+    glare.size === undefined &&
+    glare.stops === undefined
+  ) {
+    return undefined;
+  }
+  const sizeTokens = glare.size ? glare.size.trim().split(/\s+/) : [];
+  const shape = glare.shape ?? (sizeTokens.length > 1 ? "ellipse" : "circle");
+  const geometry = glare.size ? `${shape} ${glare.size}` : `${glare.extent ?? "farthest-corner"} ${shape}`;
+  const stops = (glare.stops?.length ? glare.stops : DEFAULT_GLARE_STOPS).join(", ");
+  return `radial-gradient(${geometry} at var(--pointer-x) var(--pointer-y), ${stops})`;
+};
+
+const DEPTH_VARS = ["--hc-depth", "--card-perspective", "--hc-depth-shadow", "--hc-depth-layer-scale"];
+
 interface Vec2 {
   x: number;
   y: number;
@@ -118,9 +196,8 @@ export class HoloCard {
   private readonly rotator: HTMLElement;
   private frontElement: HTMLElement | null;
   private layersElement: HTMLElement | null = null;
-  private readonly options: Required<
-    Pick<HoloCardOptions, "interactive" | "activateOnClick" | "gyroscope" | "showcase">
-  >;
+  private readonly options: Required<Pick<HoloCardOptions, "interactive" | "activateOnClick" | "showcase">>;
+  private gyroConfig: ResolvedGyroscope;
 
   private readonly springRotate: Spring<Vec2>;
   private readonly springGlare: Spring<Glare>;
@@ -177,9 +254,9 @@ export class HoloCard {
     this.options = {
       interactive: options.interactive ?? true,
       activateOnClick: options.activateOnClick ?? false,
-      gyroscope: options.gyroscope ?? true,
       showcase: options.showcase ?? false,
     };
+    this.gyroConfig = resolveGyroscope(options.gyroscope);
     this.showcaseRunning = Boolean(options.showcase);
     this.showcaseConfig = resolveShowcase(options.showcase);
 
@@ -217,6 +294,7 @@ export class HoloCard {
     } else if (!element.dataset.effect) {
       element.dataset.effect = "none";
     }
+    this.applyPalette(options.palette);
     if (options.glow) {
       element.style.setProperty("--card-glow", options.glow);
     }
@@ -226,7 +304,7 @@ export class HoloCard {
 
     const mask = normalizeMask(options.mask);
     if (mask?.image) {
-      element.style.setProperty("--mask", `url(${mask.image})`);
+      element.style.setProperty("--mask", cssUrl(mask.image));
       if (mask.size) {
         element.style.setProperty("--mask-size", mask.size);
       }
@@ -242,9 +320,11 @@ export class HoloCard {
       }
     }
     if (options.foil) {
-      element.style.setProperty("--foil", `url(${options.foil})`);
+      element.style.setProperty("--foil", cssUrl(options.foil));
     }
     this.applyVisual(options.visual);
+    this.applyGlare(options.glare);
+    this.applyDepth(options.depth);
     applyVars(element, options.vars);
 
     if (!this.layersElement && options.layers?.length && this.frontElement) {
@@ -315,6 +395,58 @@ export class HoloCard {
     }
   }
 
+  private applyPalette(palette: PaletteOptions | undefined): void {
+    if (!palette) {
+      return;
+    }
+    const style = this.element.style;
+    const vars = paletteToCssVariables(palette);
+    for (const name of PALETTE_VARIABLES) {
+      style.removeProperty(name);
+    }
+    for (const [name, value] of Object.entries(vars)) {
+      style.setProperty(name, value);
+    }
+  }
+
+  private applyGlare(glare: GlareOptions | undefined): void {
+    if (!glare) {
+      return;
+    }
+    const style = this.element.style;
+    style.removeProperty("--glare-image");
+    style.removeProperty("--glare-blend");
+    this.element.classList.remove(CLASS.customGlare);
+    if (typeof glare.opacity === "number") {
+      style.setProperty("--hc-glare-opacity", String(glare.opacity));
+    }
+    if (glare.blend !== undefined) {
+      style.setProperty("--glare-blend", glare.blend);
+    }
+    const image = composeGlareImage(glare);
+    if (image !== undefined) {
+      style.setProperty("--glare-image", image);
+      this.element.classList.add(CLASS.customGlare);
+    }
+  }
+
+  private applyDepth(depth: boolean | DepthOptions | undefined): void {
+    const style = this.element.style;
+    const config = resolveDepth(depth);
+    if (!config.enabled) {
+      this.element.classList.remove(CLASS.depth);
+      for (const name of DEPTH_VARS) {
+        style.removeProperty(name);
+      }
+      return;
+    }
+    this.element.classList.add(CLASS.depth);
+    style.setProperty("--hc-depth", `${config.strength}px`);
+    style.setProperty("--card-perspective", `${config.perspective}px`);
+    style.setProperty("--hc-depth-shadow", String(config.shadow));
+    style.setProperty("--hc-depth-layer-scale", String(config.layerScale));
+  }
+
   private applyStaticStyles(seed: number | undefined): void {
     const seedX = Math.random();
     const seedY = Math.random();
@@ -531,7 +663,7 @@ export class HoloCard {
       this.popover();
       this.element.classList.add(CLASS.active);
       this.element.style.setProperty("--card-active", "1");
-      if (this.options.gyroscope) {
+      if (this.gyroConfig.enabled) {
         this.startGyroscope();
       }
     } else {
@@ -607,20 +739,25 @@ export class HoloCard {
     if (getActiveCard() !== this) {
       return;
     }
-    const limit = { x: 16, y: 18 };
+    const gyro = this.gyroConfig;
+    const limit = { x: gyro.rangeX, y: gyro.rangeY };
+    const dirX = gyro.invertX ? -1 : 1;
+    const dirY = gyro.invertY ? -1 : 1;
     const degrees = {
-      x: clamp(orientation.relative.gamma, -limit.x, limit.x),
-      y: clamp(orientation.relative.beta, -limit.y, limit.y),
+      x: clamp(orientation.relative.gamma * gyro.sensitivity * dirX, -limit.x, limit.x),
+      y: clamp(orientation.relative.beta * gyro.sensitivity * dirY, -limit.y, limit.y),
     };
-    const gx = adjust(degrees.x, -limit.x, limit.x, 0, 100);
-    const gy = adjust(degrees.y, -limit.y, limit.y, 0, 100);
+    const fracX = limit.x === 0 ? 0 : degrees.x / limit.x;
+    const fracY = limit.y === 0 ? 0 : degrees.y / limit.y;
+    const gx = adjust(fracX, -1, 1, 0, 100);
+    const gy = adjust(fracY, -1, 1, 0, 100);
     this.setInteracting(true);
     this.updateSprings(
-      this.parallaxBackground(
-        adjust(degrees.x, -limit.x, limit.x, 37, 63),
-        adjust(degrees.y, -limit.y, limit.y, 33, 67),
-      ),
-      { x: round(degrees.x * -1 * this.tiltScaleX), y: round(degrees.y * this.tiltScaleY) },
+      this.parallaxBackground(adjust(fracX, -1, 1, 37, 63), adjust(fracY, -1, 1, 33, 67)),
+      {
+        x: round(fracX * DEFAULT_GYRO_RANGE_X * -1 * this.tiltScaleX),
+        y: round(fracY * DEFAULT_GYRO_RANGE_Y * this.tiltScaleY),
+      },
       this.rangeGlare(gx, gy, 1),
       { x: gx, y: gy },
     );
@@ -739,6 +876,47 @@ export class HoloCard {
     this.applyVisual(visual);
   }
 
+  /**
+   * Swap the foil colour palette / theme at runtime. This is a full replacement:
+   * any palette variable not present in `palette` reverts to its default.
+   */
+  setPalette(palette: PaletteOptions): void {
+    this.applyPalette(palette);
+  }
+
+  /**
+   * Update the dynamic glare (reflected light) at runtime. The image / shape /
+   * blend are replaced wholesale — omit them to return to the effect's built-in
+   * glare. `opacity` is shared with `visual.glareOpacity` and only changes when
+   * provided.
+   */
+  setGlare(glare: GlareOptions): void {
+    this.applyGlare(glare);
+  }
+
+  /** Toggle or tune the foil 3D depth / extrusion at runtime. */
+  setDepth(depth: boolean | DepthOptions): void {
+    this.applyDepth(depth);
+  }
+
+  /** Update the gyroscope physical-behaviour tuning at runtime. */
+  setGyroscope(gyroscope: boolean | GyroscopeOptions): void {
+    const wasEnabled = this.gyroConfig.enabled;
+    this.gyroConfig = resolveGyroscope(gyroscope);
+    if (getActiveCard() !== this) {
+      return;
+    }
+    if (this.gyroConfig.enabled) {
+      if (!wasEnabled) {
+        resetBaseOrientation();
+      }
+      this.startGyroscope();
+    } else {
+      this.stopGyroscope();
+      this.interactEnd(0);
+    }
+  }
+
   /**
    * Insert an extra layer between the artwork and the foil at runtime, returning
    * the created element. Requires the card to have a `.holo-card__front`.

package/src/index.ts

@@ -21,6 +21,7 @@ export {
   type Orientation,
   type RelativeOrientation,
 } from "./orientation.js";
+export { PALETTES, resolvePalette, paletteToCssVariables } from "./palette.js";
 export { getActiveCard, setActiveCard, subscribeActiveCard } from "./active-registry.js";
 export { Spring, type SpringValue, type SpringOpts, type SpringSetOpts, type SpringDynamics } from "./spring.js";
 export { round, clamp, adjust } from "./math.js";
@@ -36,6 +37,11 @@ export type {
   VisualOptions,
   MaskOptions,
   HoloLayerOptions,
+  PaletteOptions,
+  PalettePreset,
+  GlareOptions,
+  GyroscopeOptions,
+  DepthOptions,
 } from "./types.js";
 
 export const createHoloCard = (options: CreateHoloCardOptions): HoloCard => {