@kongyo2/cards-css 0.1.1 → 0.2.0

package/src/spring.ts

@@ -3,43 +3,77 @@ import { Subscribers } from "./subscribers.js";
 
 export type SpringValue = number | Record<string, number>;
 
-export interface SpringOpts {
+export interface SpringDynamics {
   stiffness?: number;
   damping?: number;
   precision?: number;
 }
 
+export interface SpringOpts extends SpringDynamics {
+  /**
+   * Per-key dynamics overrides for object springs. Each key (e.g. `x`, `y`, `o`)
+   * may carry its own stiffness/damping/precision, giving asymmetric, independent
+   * motion per axis. Keys without an entry fall back to the base dynamics.
+   */
+  axes?: Record<string, SpringDynamics>;
+}
+
 export interface SpringSetOpts {
   hard?: boolean;
   soft?: boolean | number;
 }
 
-interface TickContext {
+interface FrameContext {
   invMass: number;
   stiffness: number;
   damping: number;
   precision: number;
+  axes: Record<string, SpringDynamics> | undefined;
   settled: boolean;
   dt: number;
 }
 
-const tickScalar = (ctx: TickContext, lastValue: number, currentValue: number, targetValue: number): number => {
+interface AxisDynamics {
+  stiffness: number;
+  damping: number;
+  precision: number;
+}
+
+const tickScalar = (
+  ctx: FrameContext,
+  axis: AxisDynamics,
+  lastValue: number,
+  currentValue: number,
+  targetValue: number,
+): number => {
   const delta = targetValue - currentValue;
   const velocity = (currentValue - lastValue) / (ctx.dt || 1 / 60);
-  const spring = ctx.stiffness * delta;
-  const damper = ctx.damping * velocity;
+  const spring = axis.stiffness * delta;
+  const damper = axis.damping * velocity;
   const acceleration = (spring - damper) * ctx.invMass;
   const d = (velocity + acceleration) * ctx.dt;
-  if (Math.abs(d) < ctx.precision && Math.abs(delta) < ctx.precision) {
+  if (Math.abs(d) < axis.precision && Math.abs(delta) < axis.precision) {
     return targetValue;
   }
   ctx.settled = false;
   return currentValue + d;
 };
 
-const tick = <T extends SpringValue>(ctx: TickContext, last: T, current: T, target: T): T => {
+const resolveAxis = (ctx: FrameContext, key: string): AxisDynamics => {
+  const override = ctx.axes?.[key];
+  if (!override) {
+    return ctx;
+  }
+  return {
+    stiffness: override.stiffness ?? ctx.stiffness,
+    damping: override.damping ?? ctx.damping,
+    precision: override.precision ?? ctx.precision,
+  };
+};
+
+const tick = <T extends SpringValue>(ctx: FrameContext, last: T, current: T, target: T): T => {
   if (typeof current === "number") {
-    return tickScalar(ctx, last as number, current, target as number) as T;
+    return tickScalar(ctx, ctx, last as number, current, target as number) as T;
   }
   const cur = current as Record<string, number>;
   const lst = last as Record<string, number>;
@@ -47,7 +81,7 @@ const tick = <T extends SpringValue>(ctx: TickContext, last: T, current: T, targ
   const result: Record<string, number> = {};
   for (const key in cur) {
     const c = cur[key] ?? 0;
-    result[key] = tickScalar(ctx, lst[key] ?? c, c, tgt[key] ?? c);
+    result[key] = tickScalar(ctx, resolveAxis(ctx, key), lst[key] ?? c, c, tgt[key] ?? c);
   }
   return result as T;
 };
@@ -56,6 +90,7 @@ export class Spring<T extends SpringValue> {
   stiffness: number;
   damping: number;
   precision: number;
+  axes: Record<string, SpringDynamics> | undefined;
 
   private value: T;
   private lastValue: T;
@@ -75,6 +110,7 @@ export class Spring<T extends SpringValue> {
     this.stiffness = opts.stiffness ?? 0.15;
     this.damping = opts.damping ?? 0.8;
     this.precision = opts.precision ?? 0.01;
+    this.axes = opts.axes;
   }
 
   get current(): T {
@@ -123,11 +159,12 @@ export class Spring<T extends SpringValue> {
           return false;
         }
         this.invMass = Math.min(this.invMass + this.invMassRecoveryRate, 1);
-        const ctx: TickContext = {
+        const ctx: FrameContext = {
           invMass: this.invMass,
           stiffness: this.stiffness,
           damping: this.damping,
           precision: this.precision,
+          axes: this.axes,
           settled: true,
           dt: ((time - this.lastTime) * 60) / 1000,
         };

package/src/styles/base.css

@@ -32,6 +32,11 @@
   --pointer-from-center: 0;
   --pointer-from-top: var(--pointer-from-center);
   --pointer-from-left: var(--pointer-from-center);
+  --pointer-dx: 0;
+  --pointer-dy: 0;
+  --tilt-x: 0;
+  --tilt-y: 0;
+  --card-active: 0;
 }
 
 .holo-card {
@@ -43,6 +48,22 @@
   --angle: 133deg;
   --imgsize: cover;
 
+  --hc-brightness: 1;
+  --hc-contrast: 1;
+  --hc-saturate: 1;
+  --hc-glare-opacity: 1;
+  --hc-shine-opacity: 1;
+
+  --mask-size: cover;
+  --mask-position: center center;
+  --mask-repeat: no-repeat;
+
+  --layer-blend: normal;
+  --layer-size: cover;
+  --layer-position: center;
+  --layer-opacity: 1;
+  --layer-parallax: 0;
+
   --red: #f80e35;
   --yellow: #eedf10;
   --green: #21e985;
@@ -173,6 +194,11 @@ button.holo-card__rotator {
   transform: translate3d(0px, 0px, 0.01px);
 }
 
+.holo-card__rotator img.holo-card__image {
+  height: 100%;
+  object-fit: var(--imgsize);
+}
+
 .holo-card__back {
   background-color: var(--card-back);
   transform: rotateY(180deg) translateZ(1px);
@@ -212,9 +238,10 @@ button.holo-card__rotator {
   background: transparent;
   background-size: cover;
   background-position: center;
-  filter: brightness(0.85) contrast(2.75) saturate(0.65);
+  filter: brightness(calc(0.85 * var(--hc-brightness))) contrast(calc(2.75 * var(--hc-contrast)))
+    saturate(calc(0.65 * var(--hc-saturate)));
   mix-blend-mode: color-dodge;
-  opacity: var(--card-opacity);
+  opacity: calc(var(--card-opacity) * var(--hc-shine-opacity));
 }
 
 .holo-card__shine::before,
@@ -249,7 +276,7 @@ button.holo-card__rotator {
     hsla(0, 0%, 100%, 0.65) 20%,
     hsla(0, 0%, 0%, 0.5) 90%
   );
-  opacity: var(--card-opacity);
+  opacity: calc(var(--card-opacity) * var(--hc-glare-opacity));
   mix-blend-mode: overlay;
 }
 
@@ -257,6 +284,68 @@ button.holo-card__rotator {
 .holo-card--masked .holo-card__shine::before,
 .holo-card--masked .holo-card__shine::after {
   mask-image: var(--mask);
+  mask-size: var(--mask-size);
+  mask-position: var(--mask-position);
+  mask-repeat: var(--mask-repeat);
+}
+
+.holo-card--mask-card .holo-card__front,
+.holo-card--mask-card .holo-card__back {
+  mask-image: var(--mask);
+  mask-size: var(--mask-size);
+  mask-position: var(--mask-position);
+  mask-repeat: var(--mask-repeat);
+}
+
+.holo-card__layers {
+  z-index: 2;
+  pointer-events: none;
+}
+
+.holo-card__layer {
+  grid-area: 1/1;
+  background-image: var(--layer-image, none);
+  background-size: var(--layer-size);
+  background-position: var(--layer-position);
+  background-repeat: no-repeat;
+  mix-blend-mode: var(--layer-blend);
+  opacity: var(--layer-opacity);
+  transform: translate3d(
+    calc(var(--pointer-dx) * var(--layer-parallax) * 1px),
+    calc(var(--pointer-dy) * var(--layer-parallax) * 1px),
+    0.02px
+  );
+  will-change: transform, opacity;
+}
+
+.holo-card__layer--masked {
+  mask-image: var(--layer-mask);
   mask-size: cover;
-  mask-position: center center;
+  mask-position: center;
+}
+
+.holo-card__content {
+  transform: translate3d(0px, 0px, 0.01px);
+}
+
+.holo-card__content *,
+.holo-card__overlay *,
+.holo-card__layer * {
+  width: auto;
+  display: revert;
+  grid-area: auto;
+  aspect-ratio: auto;
+  overflow: revert;
+  border-radius: revert;
+}
+
+.holo-card__overlay {
+  z-index: 4;
+  transform: translateZ(2px);
+  pointer-events: none;
+}
+
+.holo-card__overlay--interactive,
+.holo-card__overlay--interactive * {
+  pointer-events: auto;
 }

package/src/styles/effects/cosmos.css

@@ -1,10 +1,13 @@
-.holo-card[data-effect="cosmos"] .holo-card__shine {
+.holo-card[data-effect="cosmos"] {
   --space: 4%;
+  --angle: 82deg;
+}
 
+.holo-card[data-effect="cosmos"] .holo-card__shine {
   background-image:
     var(--hc-cosmos-bottom),
     repeating-linear-gradient(
-      82deg,
+      var(--angle),
       hsl(53, 65%, 60%) calc(var(--space) * 1),
       hsl(93, 56%, 50%) calc(var(--space) * 2),
       hsl(176, 54%, 49%) calc(var(--space) * 3),
@@ -37,7 +40,7 @@
     400% 900%,
     cover;
 
-  filter: brightness(1) contrast(1) saturate(0.8);
+  filter: brightness(var(--hc-brightness)) contrast(var(--hc-contrast)) saturate(calc(0.8 * var(--hc-saturate)));
   mix-blend-mode: color-dodge;
 }
 
@@ -48,7 +51,7 @@
   background-image:
     var(--hc-cosmos-middle),
     repeating-linear-gradient(
-      82deg,
+      var(--angle),
       hsl(53, 65%, 60%) calc(var(--space) * 1),
       hsl(93, 56%, 50%) calc(var(--space) * 2),
       hsl(176, 54%, 49%) calc(var(--space) * 3),
@@ -86,7 +89,7 @@
   background-image:
     var(--hc-cosmos-top),
     repeating-linear-gradient(
-      82deg,
+      var(--angle),
       hsl(53, 65%, 60%) calc(var(--space) * 1),
       hsl(93, 56%, 50%) calc(var(--space) * 2),
       hsl(176, 54%, 49%) calc(var(--space) * 3),
@@ -125,7 +128,7 @@
   );
   filter: brightness(0.75) contrast(2) saturate(2);
   mix-blend-mode: overlay;
-  opacity: calc(var(--card-opacity) * (0.25 + var(--pointer-from-center)));
+  opacity: calc(var(--card-opacity) * (0.25 + var(--pointer-from-center)) * var(--hc-glare-opacity));
 }
 
 .holo-card[data-effect="cosmos"] .holo-card__glare::after {

package/src/styles/effects/glitter.css

@@ -17,7 +17,7 @@
     55% 55%,
     center center;
   background-blend-mode: soft-light, color-burn;
-  filter: brightness(1) contrast(1) saturate(0.9);
+  filter: brightness(var(--hc-brightness)) contrast(var(--hc-contrast)) saturate(calc(0.9 * var(--hc-saturate)));
 }
 
 .holo-card[data-effect="glitter"] .holo-card__shine::before {
@@ -88,7 +88,9 @@
 .holo-card--masked[data-effect="glitter"] .holo-card__glare::after {
   content: "";
   mask-image: var(--mask);
-  mask-size: cover;
+  mask-size: var(--mask-size);
+  mask-position: var(--mask-position);
+  mask-repeat: var(--mask-repeat);
 
   background-image: radial-gradient(
     farthest-corner circle at var(--pointer-x) var(--pointer-y),

package/src/styles/effects/holo.css

@@ -43,7 +43,8 @@
     cover;
 
   background-blend-mode: overlay;
-  filter: brightness(1.1) contrast(1.1) saturate(1.2);
+  filter: brightness(calc(1.1 * var(--hc-brightness))) contrast(calc(1.1 * var(--hc-contrast)))
+    saturate(calc(1.2 * var(--hc-saturate)));
   mix-blend-mode: color-dodge;
 }
 
@@ -107,7 +108,7 @@
 }
 
 .holo-card[data-effect="holo"] .holo-card__glare {
-  opacity: calc(var(--card-opacity) * 0.8);
+  opacity: calc(var(--card-opacity) * 0.8 * var(--hc-glare-opacity));
   filter: brightness(0.8) contrast(1.5);
   mix-blend-mode: overlay;
 }

package/src/styles/effects/reverse.css

@@ -17,14 +17,15 @@
     calc(100% * var(--pointer-from-left)) calc(100% * var(--pointer-from-top)),
     center center;
 
-  filter: brightness(var(--foil-brightness)) contrast(1.5) saturate(1);
+  filter: brightness(calc(var(--foil-brightness) * var(--hc-brightness))) contrast(calc(1.5 * var(--hc-contrast)))
+    saturate(var(--hc-saturate));
   mix-blend-mode: color-dodge;
 
-  opacity: calc((1.5 * var(--card-opacity)) - var(--pointer-from-center));
+  opacity: calc(((1.5 * var(--card-opacity)) - var(--pointer-from-center)) * var(--hc-shine-opacity));
 }
 
 .holo-card[data-effect="reverse"] .holo-card__glare {
-  opacity: var(--card-opacity);
+  opacity: calc(var(--card-opacity) * var(--hc-glare-opacity));
 
   background-image: radial-gradient(
     farthest-corner circle at var(--pointer-x) var(--pointer-y),

package/src/types.ts

@@ -1,22 +1,170 @@
+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 });