@kongyo2/cards-css 0.1.0 → 0.2.0

package/dist-types/types.d.ts

@@ -1,21 +1,164 @@
+import type { SpringOpts } from "./spring.js";
 export type HoloEffect = "none" | "holo" | "reverse" | "cosmos" | "glitter";
+/**
+ * Arbitrary card content: a DOM node, or a factory that builds one from the
+ * owning document (handy for SSR / custom-element setups where `document` is
+ * only safe to touch lazily).
+ */
+export type HoloContent = Node | ((doc: Document) => Node);
+/** A map of CSS custom properties to apply to an element; numbers are stringified. */
+export type CssVars = Record<string, string | number>;
+/**
+ * Spring tuning for a single motion target. `axes` carries independent,
+ * asymmetric dynamics per component (`x` / `y` / `o`).
+ */
+export type SpringTuning = SpringOpts;
+/** Interaction & physics adjustment surface. */
+export interface PhysicsOptions {
+    /** Tilt in degrees reached at the card edge (default ≈ 14.29). */
+    maxTilt?: number;
+    /** Independent horizontal tilt; overrides `maxTilt` for the X axis. */
+    maxTiltX?: number;
+    /** Independent vertical tilt; overrides `maxTilt` for the Y axis. */
+    maxTiltY?: number;
+    /** Multiplier on the foil/background parallax shift (default 1; 0 disables). */
+    parallax?: number;
+    /** Multiplier on the glare travel away from centre (default 1). */
+    glareRange?: number;
+    /** ms to wait after the pointer leaves before the relaxed snap-back (default 500). */
+    returnDelay?: number;
+    /** Tuning shared by the live pointer springs (rotate / glare / background). */
+    interactSpring?: SpringTuning;
+    /** Tuning shared by the popover springs (scale / translate / flip). */
+    popoverSpring?: SpringTuning;
+    /** Tuning for the relaxed snap-back applied when the pointer leaves. */
+    snapSpring?: SpringTuning;
+    /** Per-target overrides layered on top of the group tuning above. */
+    springs?: {
+        rotate?: SpringTuning;
+        glare?: SpringTuning;
+        background?: SpringTuning;
+        rotateDelta?: SpringTuning;
+        translate?: SpringTuning;
+        scale?: SpringTuning;
+    };
+}
+/** Showcase (auto-animation) customisation. `true` keeps the legacy defaults. */
+export interface ShowcaseOptions {
+    /** ms before the sweep begins (default 2000). */
+    delay?: number;
+    /** ms the sweep runs before relaxing; ignored when `loop` is set (default 4000). */
+    duration?: number;
+    /** Keep sweeping until the user interacts instead of running once (default false). */
+    loop?: boolean;
+    /** Angular step per tick — higher is faster (default 0.05). */
+    speed?: number;
+    /** Tilt amplitude in degrees (default 25). */
+    intensity?: number;
+    /** Spring tuning while the showcase runs. */
+    spring?: SpringTuning;
+}
+/** Fine-grained visual / effect control. Numeric fields are multipliers (1 = unchanged). */
+export interface VisualOptions {
+    /** Foil brightness multiplier. */
+    brightness?: number;
+    /** Foil contrast multiplier. */
+    contrast?: number;
+    /** Foil saturation multiplier. */
+    saturate?: number;
+    /** Glare layer opacity multiplier. */
+    glareOpacity?: number;
+    /** Shine/foil layer opacity multiplier. */
+    shineOpacity?: number;
+    /** Foil line spacing for the glitter/cosmos foils (`--space`); a number is read as a percentage. */
+    lineSpace?: string | number;
+    /** Foil sweep angle for the glitter/cosmos foils (`--angle`); a number is read as degrees. */
+    lineAngle?: string | number;
+    /** Glitter cell size (`--glittersize`); a number is read as a percentage. */
+    glitterSize?: string | number;
+    /** Artwork object-fit (`--imgsize`, default `cover`). */
+    imageFit?: string;
+}
+/** Advanced mask processing. A bare string is shorthand for `{ image }`. */
+export interface MaskOptions {
+    /** Mask image URL. */
+    image?: string;
+    /** `mask-size` (default `cover`). */
+    size?: string;
+    /** `mask-position` (default `center center`). */
+    position?: string;
+    /** `mask-repeat` (default `no-repeat`). */
+    repeat?: string;
+    /**
+     * What the mask clips:
+     * - `shine` (default) clips only the foil, as before;
+     * - `card` clips the whole card into the mask silhouette (artwork included).
+     */
+    mode?: "shine" | "card";
+}
+/** An extra stacked layer between the artwork and the foil. */
+export interface HoloLayerOptions {
+    /** Image URL painted into the layer. */
+    image?: string;
+    /** Arbitrary content for the layer (overrides `image`). */
+    content?: HoloContent;
+    /** `mix-blend-mode` for the layer (default `normal`). */
+    blend?: string;
+    /** Layer opacity 0–1 (default 1). */
+    opacity?: number;
+    /** Pointer-driven parallax depth in px; the layer drifts with the tilt (default 0). */
+    parallax?: number;
+    /** Per-layer mask image URL. */
+    mask?: string;
+    /** `background-size` when an `image` is used (default `cover`). */
+    size?: string;
+    /** `background-position` when an `image` is used (default `center`). */
+    position?: string;
+    /** Extra class names for the layer element. */
+    className?: string;
+    /** Extra CSS custom properties for the layer element. */
+    vars?: CssVars;
+}
 export interface HoloCardOptions {
     effect?: HoloEffect;
     interactive?: boolean;
     activateOnClick?: boolean;
     gyroscope?: boolean;
-    showcase?: boolean;
+    showcase?: boolean | ShowcaseOptions;
     glow?: string;
     aspectRatio?: number;
     textureSeed?: number;
-    mask?: string;
+    mask?: string | MaskOptions;
     foil?: string;
+    /** Interaction & physics adjustments. */
+    physics?: PhysicsOptions;
+    /** Fine-grained visual control. */
+    visual?: VisualOptions;
+    /** Extra stacked layers between the artwork and the foil. */
+    layers?: HoloLayerOptions[];
+    /** Arbitrary CSS custom properties applied to the root (for content linkage). */
+    vars?: CssVars;
 }
-export interface CreateHoloCardOptions extends HoloCardOptions {
-    image: string;
+export interface CreateHoloCardFields extends HoloCardOptions {
     imageAlt?: string;
     back?: string;
     backAlt?: string;
+    /** Foreground content above the foil — name plates, badges, live data, etc. */
+    overlay?: HoloContent;
+    /** Let the overlay receive pointer events (default false: purely decorative). */
+    overlayInteractive?: boolean;
     className?: string;
 }
+/**
+ * Options for `createHoloCard`. Either `image` (front artwork) or `content`
+ * (custom front content) must be supplied — both may be combined — so the card
+ * is never built blank.
+ */
+export type CreateHoloCardOptions = CreateHoloCardFields & ({
+    image: string;
+    content?: HoloContent;
+} | {
+    image?: string;
+    content: HoloContent;
+});
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"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.1.0",
+  "version": "0.2.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

@@ -1,4 +1,4 @@
-import type { CreateHoloCardOptions } from "./types.js";
+import type { CreateHoloCardOptions, CssVars, HoloContent, HoloLayerOptions, MaskOptions } from "./types.js";
 
 export const CLASS = {
   root: "holo-card",
@@ -7,6 +7,10 @@ export const CLASS = {
   front: "holo-card__front",
   back: "holo-card__back",
   image: "holo-card__image",
+  content: "holo-card__content",
+  layers: "holo-card__layers",
+  layer: "holo-card__layer",
+  overlay: "holo-card__overlay",
   shine: "holo-card__shine",
   glare: "holo-card__glare",
   interactive: "holo-card--interactive",
@@ -14,6 +18,8 @@ export const CLASS = {
   interacting: "holo-card--interacting",
   loading: "holo-card--loading",
   masked: "holo-card--masked",
+  maskCard: "holo-card--mask-card",
+  overlayInteractive: "holo-card__overlay--interactive",
 } as const;
 
 const requireDocument = (): Document => {
@@ -23,19 +29,98 @@ const requireDocument = (): Document => {
   return document;
 };
 
+export const applyVars = (element: HTMLElement, vars: CssVars | undefined): void => {
+  if (!vars) {
+    return;
+  }
+  for (const [name, value] of Object.entries(vars)) {
+    const property = name.startsWith("--") ? name : `--${name}`;
+    element.style.setProperty(property, typeof value === "number" ? String(value) : value);
+  }
+};
+
+export interface ResolvedMask {
+  image: string | undefined;
+  size: string | undefined;
+  position: string | undefined;
+  repeat: string | undefined;
+  mode: NonNullable<MaskOptions["mode"]>;
+}
+
+export const normalizeMask = (mask: string | MaskOptions | undefined): ResolvedMask | null => {
+  if (!mask) {
+    return null;
+  }
+  const opts: MaskOptions = typeof mask === "string" ? { image: mask } : mask;
+  if (!opts.image) {
+    return null;
+  }
+  return {
+    image: opts.image,
+    size: opts.size,
+    position: opts.position,
+    repeat: opts.repeat,
+    mode: opts.mode ?? "shine",
+  };
+};
+
+const addClasses = (element: HTMLElement, className: string | undefined): void => {
+  if (!className) {
+    return;
+  }
+  for (const name of className.split(/\s+/).filter(Boolean)) {
+    element.classList.add(name);
+  }
+};
+
+const resolveContent = (doc: Document, content: HoloContent): Node =>
+  typeof content === "function" ? content(doc) : content;
+
+export const buildLayerElement = (doc: Document, layer: HoloLayerOptions): HTMLElement => {
+  const el = doc.createElement("div");
+  el.className = CLASS.layer;
+  addClasses(el, layer.className);
+
+  if (typeof layer.blend === "string") {
+    el.style.setProperty("--layer-blend", layer.blend);
+  }
+  if (typeof layer.opacity === "number") {
+    el.style.setProperty("--layer-opacity", String(layer.opacity));
+  }
+  if (typeof layer.parallax === "number") {
+    el.style.setProperty("--layer-parallax", String(layer.parallax));
+  }
+  if (layer.mask) {
+    el.style.setProperty("--layer-mask", `url(${layer.mask})`);
+    el.classList.add(`${CLASS.layer}--masked`);
+  }
+  if (layer.image) {
+    el.style.setProperty("--layer-image", `url(${layer.image})`);
+    el.style.setProperty("--layer-size", layer.size ?? "cover");
+    el.style.setProperty("--layer-position", layer.position ?? "center");
+  }
+  applyVars(el, layer.vars);
+
+  if (layer.content) {
+    el.appendChild(resolveContent(doc, layer.content));
+  }
+  return el;
+};
+
 export const buildHoloCardElement = (options: CreateHoloCardOptions): HTMLElement => {
   const doc = requireDocument();
 
   const root = doc.createElement("div");
   root.className = CLASS.root;
-  if (options.className) {
-    for (const name of options.className.split(/\s+/).filter(Boolean)) {
-      root.classList.add(name);
-    }
-  }
+  addClasses(root, options.className);
   root.dataset.effect = options.effect ?? "none";
-  if (options.mask) {
+
+  const mask = normalizeMask(options.mask);
+  if (mask) {
     root.classList.add(CLASS.masked);
+    if (mask.mode === "card") {
+      root.classList.add(CLASS.maskCard);
+    }
   }
 
   const translater = doc.createElement("div");
@@ -56,12 +141,30 @@ export const buildHoloCardElement = (options: CreateHoloCardOptions): HTMLElemen
   const front = doc.createElement("div");
   front.className = CLASS.front;
 
-  const image = doc.createElement("img");
-  image.className = CLASS.image;
-  image.src = options.image;
-  image.alt = options.imageAlt ?? "";
-  image.loading = "lazy";
-  front.appendChild(image);
+  if (options.image) {
+    const image = doc.createElement("img");
+    image.className = CLASS.image;
+    image.src = options.image;
+    image.alt = options.imageAlt ?? "";
+    image.loading = "lazy";
+    front.appendChild(image);
+  }
+
+  if (options.content) {
+    const content = doc.createElement("div");
+    content.className = CLASS.content;
+    content.appendChild(resolveContent(doc, options.content));
+    front.appendChild(content);
+  }
+
+  if (options.layers?.length) {
+    const layers = doc.createElement("div");
+    layers.className = CLASS.layers;
+    for (const layer of options.layers) {
+      layers.appendChild(buildLayerElement(doc, layer));
+    }
+    front.appendChild(layers);
+  }
 
   const shine = doc.createElement("div");
   shine.className = CLASS.shine;
@@ -71,6 +174,17 @@ export const buildHoloCardElement = (options: CreateHoloCardOptions): HTMLElemen
 
   front.appendChild(shine);
   front.appendChild(glare);
+
+  if (options.overlay) {
+    const overlay = doc.createElement("div");
+    overlay.className = CLASS.overlay;
+    if (options.overlayInteractive) {
+      overlay.classList.add(CLASS.overlayInteractive);
+    }
+    overlay.appendChild(resolveContent(doc, options.overlay));
+    front.appendChild(overlay);
+  }
+
   rotator.appendChild(front);
   translater.appendChild(rotator);
   root.appendChild(translater);