@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/components/core/Dropdown/DropdownTrigger.d.ts

@@ -1,9 +1,14 @@
 import React from "react";
 import { DropdownTriggerProps } from "./Dropdown.types";
+export interface TriggerChildProps {
+    className?: string;
+    onClick?: (e: React.MouseEvent) => void;
+    ref?: React.Ref<HTMLElement>;
+}
 /**
  * DropdownTrigger component - wraps the trigger element
  */
 export declare const DropdownTrigger: {
-    ({ children, className }: DropdownTriggerProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+    ({ children, className }: DropdownTriggerProps): React.ReactElement<TriggerChildProps, string | React.JSXElementConstructor<any>>;
     displayName: string;
 };

package/dist/components/core/Dropdown/DropdownTrigger.js

@@ -1,21 +1,51 @@
+"use client";
 import React__default, { useCallback } from 'react';
+import { cn } from '../../../utils/cn.js';
 import { useDropdownContext } from './DropdownContext.js';
 
+/**
+ * Default interaction treatment applied to EVERY trigger so a dropdown opener shows a
+ * consistent active state for free — no per-usage classes. Hover AND open both paint the
+ * single `--color-surface-hover` interaction tint (§3), so the two read identically (the
+ * trigger doesn't visually "change" when you hover an already-open menu).
+ *
+ * 🔴 Keyed on `aria-expanded`, NOT `data-[state=open]`: a `Button` trigger overwrites its own
+ * `data-state` (idle/loading), clobbering the open flag — `aria-expanded` is the reliable hook.
+ *
+ * Injected FIRST in the className merge, so a consumer's own `className` on the trigger child
+ * always wins (shadcn override model).
+ *
+ * 🔴 Applied ONLY to non-`Button` triggers. A `Button` is a complete, self-styled component
+ * (its own hover/active/variant states), and a *filled* Button hovers via a `brightness` filter
+ * rather than a `hover:bg-*`, so this translucent tint would have nothing to override and would
+ * replace the Button's solid fill on hover/open (a filled trigger going see-through). Buttons
+ * therefore keep their own styling; this convenience tint is for plain/custom trigger elements
+ * that have no interaction state of their own.
+ */
+const triggerInteractionStyle = "hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text-primary)] " +
+    "dark:hover:bg-[var(--color-surface-hover)] " +
+    "aria-[expanded=true]:bg-[var(--color-surface-hover)] aria-[expanded=true]:text-[var(--color-text-primary)]";
 /**
  * DropdownTrigger component - wraps the trigger element
  */
 const DropdownTrigger = ({ children, className }) => {
-    var _a;
-    const { isOpen, onOpenChange, triggerRef } = useDropdownContext();
+    var _a, _b;
+    const { isOpen, onOpenChange, triggerRef, menuId } = useDropdownContext();
     const handleClick = useCallback(() => {
         onOpenChange(!isOpen);
     }, [isOpen, onOpenChange]);
+    const childElement = children;
+    // A Button trigger brings its own complete interaction styling — don't inject
+    // the default tint over it (it would override a filled Button's fill). See the
+    // note on triggerInteractionStyle above.
+    const isButtonChild = React__default.isValidElement(childElement) &&
+        ((_a = childElement.type) === null || _a === void 0 ? void 0 : _a.displayName) === "Button";
     // Clone the child element and add our props
-    const trigger = React__default.cloneElement(children, {
+    const trigger = React__default.cloneElement(childElement, {
         ref: (el) => {
             triggerRef.current = el;
             // Preserve any existing ref from the child
-            const childRef = children.ref;
+            const childRef = childElement.ref;
             if (typeof childRef === "function") {
                 childRef(el);
             }
@@ -24,21 +54,24 @@ const DropdownTrigger = ({ children, className }) => {
             }
         },
         onClick: (e) => {
+            var _a;
             // Call our handler
             handleClick();
             // Preserve any existing onClick from the child
-            const childProps = children.props;
-            if (childProps === null || childProps === void 0 ? void 0 : childProps.onClick) {
-                childProps.onClick(e);
+            if ((_a = childElement.props) === null || _a === void 0 ? void 0 : _a.onClick) {
+                childElement.props.onClick(e);
             }
         },
         "aria-expanded": isOpen,
         "aria-haspopup": "menu",
+        "aria-controls": isOpen ? menuId : undefined,
         "data-state": isOpen ? "open" : "closed",
-        className: className || ((_a = children.props) === null || _a === void 0 ? void 0 : _a.className),
+        // Default interaction style first → child's own className (and the Trigger's
+        // `className` prop) override it. Skipped for Button children (they self-style).
+        className: cn(!isButtonChild && triggerInteractionStyle, (_b = childElement.props) === null || _b === void 0 ? void 0 : _b.className, className),
     });
     return trigger;
 };
-DropdownTrigger.displayName = "DropdownTrigger";
+DropdownTrigger.displayName = "Dropdown.Trigger";
 
 export { DropdownTrigger };

package/dist/components/core/Empty/Empty.js

@@ -11,7 +11,7 @@ const Empty = React__default.forwardRef(({ title, subtitle, image, imageAlt, ico
     if (children) {
         return (jsx("div", { ref: ref, className: cn(emptyTheme.baseStyle, className), role: "region", "aria-label": "Empty state", ...props, children: children }));
     }
-    return (jsxs("div", { ref: ref, className: cn(emptyTheme.baseStyle, className), role: "region", "aria-label": "Empty state", ...props, children: [image ? (jsx("div", { className: "flex-shrink-0 mb-6", children: jsx("img", { src: image, alt: imageAlt || "Empty state illustration", className: cn("mx-auto object-cover", imageDimensions), loading: "lazy" }) })) : icon ? (jsx("div", { className: cn("flex-shrink-0 mx-auto text-[var(--color-text-muted)] mb-6", iconDimensions), "aria-hidden": "true", children: icon })) : null, jsxs("div", { className: "flex flex-col items-center justify-center gap-1", children: [title && jsx("div", { className: emptyTheme.titleStyle, children: title }), subtitle && (jsx("div", { className: emptyTheme.subtitleStyle, children: subtitle }))] }), action && (jsx("div", { className: "flex flex-col sm:flex-row gap-2 justify-center items-center mt-3", children: action }))] }));
+    return (jsxs("div", { ref: ref, className: cn(emptyTheme.baseStyle, className), role: "region", "aria-label": "Empty state", ...props, children: [image ? (jsx("div", { className: "flex-shrink-0 mb-6", children: jsx("img", { src: image, alt: imageAlt || "Empty state illustration", className: cn("mx-auto object-cover", imageDimensions), loading: "lazy" }) })) : icon ? (jsx("div", { className: cn("flex-shrink-0 mx-auto flex items-center justify-center text-[var(--color-text-muted)] mb-6", iconDimensions), "aria-hidden": "true", children: icon })) : null, jsxs("div", { className: "flex flex-col items-center justify-center gap-1", children: [title && jsx("div", { className: emptyTheme.titleStyle, children: title }), subtitle && (jsx("div", { className: emptyTheme.subtitleStyle, children: subtitle }))] }), action && (jsx("div", { className: "flex flex-col sm:flex-row gap-2 justify-center items-center mt-3", children: action }))] }));
 });
 // Set display name for dev tools and Storybook
 Empty.displayName = "Empty";

package/dist/components/core/Empty/Empty.theme.js

@@ -5,7 +5,7 @@ const emptyTheme = {
     // Base container styles - customizable spacing, colors, and layout
     baseStyle: "flex flex-col items-center justify-center text-center w-full max-w-md mx-auto space-y-3 py-12 px-6 ",
     // Title text styles - customizable typography and colors
-    titleStyle: "text-base font-semibold text-[var(--color-text-primary)]",
+    titleStyle: "text-sm font-semibold text-[var(--color-text-primary)]",
     // Description text styles - customizable typography and colors
     subtitleStyle: "text-sm text-[var(--color-text-muted)]",
 };

package/dist/components/core/HeroCard/HeroCard.d.ts

@@ -0,0 +1,5 @@
+import React from "react";
+import type { HeroCardProps } from "./HeroCard.types";
+/** Default backdrop — one of the bundled `@flikk/ui/bg/*` blobs. */
+export declare const HERO_CARD_DEFAULT_IMAGE = "/bg/1.webp";
+export declare const HeroCard: React.ForwardRefExoticComponent<HeroCardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/HeroCard/HeroCard.js

@@ -0,0 +1,100 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useRef, useCallback, useEffect } from 'react';
+import { useReducedMotion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { heroCardTheme } from './HeroCard.theme.js';
+
+/** Default backdrop — one of the bundled `@flikk/ui/bg/*` blobs. */
+const HERO_CARD_DEFAULT_IMAGE = "/bg/1.webp";
+const HeroCard = React__default.forwardRef(({ image = HERO_CARD_DEFAULT_IMAGE, imageBlur = 40, imageScale = 1.5, imageOpacity = 0.25, imageBlend = "multiply", imagePosition = "center", parallax = false, parallaxIntensity = 32, contentClassName, theme, className, children, ...rest }, ref) => {
+    const outerRef = useRef(null);
+    const bgRef = useRef(null);
+    // Merge the forwarded ref with our internal one (we need the node for the listener)
+    const setOuterRef = useCallback((node) => {
+        outerRef.current = node;
+        if (typeof ref === "function")
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [ref]);
+    const prefersReducedMotion = useReducedMotion();
+    const parallaxOn = parallax && !!image && !prefersReducedMotion;
+    // Resting transform — also the SSR/no-JS value; the parallax loop overrides it imperatively.
+    const baseTransform = imageScale !== 1 ? `scale(${imageScale})` : undefined;
+    useEffect(() => {
+        const outer = outerRef.current;
+        const bg = bgRef.current;
+        if (!parallaxOn || !outer || !bg)
+            return;
+        let disposed = false;
+        // Travel can't exceed the overscan or the card edge would show through.
+        const maxTravel = (size) => Math.min(parallaxIntensity, ((imageScale - 1) / 2) * size);
+        let pointer = null;
+        const st = { tx: 0, ty: 0, x: 0, y: 0, raf: 0, running: false, last: 0 };
+        const apply = () => {
+            bg.style.transform = `translate3d(${st.x.toFixed(2)}px, ${st.y.toFixed(2)}px, 0) scale(${imageScale})`;
+        };
+        const loop = (now) => {
+            if (disposed)
+                return;
+            const dt = Math.min(Math.max((now - st.last) / 1000, 0.001), 0.05);
+            st.last = now;
+            const a = 1 - Math.exp(-9 * dt); // dt-normalized easing — same feel at 60/120Hz
+            st.x += (st.tx - st.x) * a;
+            st.y += (st.ty - st.y) * a;
+            apply();
+            if (Math.abs(st.tx - st.x) < 0.1 && Math.abs(st.ty - st.y) < 0.1 && !pointer) {
+                st.running = false;
+                return; // settled at rest, pointer gone → idle (no per-frame cost)
+            }
+            st.raf = requestAnimationFrame(loop);
+        };
+        const start = () => {
+            if (st.running || disposed)
+                return;
+            st.running = true;
+            st.last = performance.now();
+            st.raf = requestAnimationFrame(loop);
+        };
+        const onMove = (e) => {
+            if (e.pointerType !== "mouse")
+                return;
+            const r = outer.getBoundingClientRect();
+            pointer = { x: e.clientX, y: e.clientY };
+            const nx = (e.clientX - r.left) / r.width - 0.5; // -0.5 … 0.5
+            const ny = (e.clientY - r.top) / r.height - 0.5;
+            // Opposite the cursor → parallax depth; full intensity at the edges.
+            st.tx = -nx * 2 * maxTravel(r.width);
+            st.ty = -ny * 2 * maxTravel(r.height);
+            start();
+        };
+        const onLeave = () => {
+            pointer = null;
+            st.tx = 0;
+            st.ty = 0;
+            start(); // ease back to rest, then the loop self-stops
+        };
+        outer.addEventListener("pointermove", onMove, { passive: true });
+        outer.addEventListener("pointerleave", onLeave);
+        return () => {
+            disposed = true;
+            outer.removeEventListener("pointermove", onMove);
+            outer.removeEventListener("pointerleave", onLeave);
+            cancelAnimationFrame(st.raf);
+            bg.style.transform = baseTransform !== null && baseTransform !== void 0 ? baseTransform : "";
+        };
+    }, [parallaxOn, imageScale, parallaxIntensity, baseTransform]);
+    return (jsxs("div", { ref: setOuterRef, className: cn(heroCardTheme.baseStyle, theme === null || theme === void 0 ? void 0 : theme.baseStyle, className), ...rest, children: [image && (jsx("div", { ref: bgRef, "aria-hidden": "true", className: cn(heroCardTheme.imageStyle, theme === null || theme === void 0 ? void 0 : theme.imageStyle), style: {
+                    backgroundImage: `url(${image})`,
+                    backgroundPosition: imagePosition,
+                    // Numeric knobs go inline — no dynamic Tailwind classes to purge-miss.
+                    filter: imageBlur > 0 ? `blur(${imageBlur}px)` : undefined,
+                    transform: baseTransform,
+                    opacity: imageOpacity,
+                    mixBlendMode: imageBlend,
+                } })), jsx("div", { className: cn(heroCardTheme.contentStyle, theme === null || theme === void 0 ? void 0 : theme.contentStyle, contentClassName), children: children })] }));
+});
+HeroCard.displayName = "HeroCard";
+
+export { HERO_CARD_DEFAULT_IMAGE, HeroCard };

package/dist/components/core/HeroCard/HeroCard.theme.d.ts

@@ -0,0 +1,3 @@
+import type { HeroCardThemeOverrides } from "./HeroCard.types";
+export type HeroCardTheme = Required<HeroCardThemeOverrides>;
+export declare const heroCardTheme: HeroCardTheme;

package/dist/components/core/HeroCard/HeroCard.theme.js

@@ -0,0 +1,11 @@
+const heroCardTheme = {
+    // Shares --card-radius (HeroCard is a Card presentation, not a distinct
+    // container) — a consumer overrides per-instance via `className`, same as
+    // every other component (shadcn override pattern).
+    // Gradient runs on the primary scale so it follows the app theme.
+    baseStyle: "relative overflow-hidden rounded-[var(--card-radius)] p-10 text-[var(--color-primary-contrast)] bg-gradient-to-br from-[var(--color-primary-600)] via-[var(--color-primary-700)] to-[var(--color-primary-500)] ring-4 ring-[var(--color-primary)]/20 ",
+    imageStyle: "absolute inset-0 z-0 pointer-events-none bg-cover",
+    contentStyle: "relative z-10",
+};
+
+export { heroCardTheme };

package/dist/components/core/HeroCard/HeroCard.types.d.ts

@@ -0,0 +1,70 @@
+import React from "react";
+/** How the backdrop image composites over the gradient fill. */
+export type HeroCardBlendMode = "multiply" | "overlay" | "soft-light" | "hard-light" | "screen" | "luminosity" | "normal";
+export interface HeroCardThemeOverrides {
+    baseStyle?: string;
+    imageStyle?: string;
+    contentStyle?: string;
+}
+/**
+ * HeroCard — a gradient hero shell with an ambient blurred backdrop image.
+ * Children are the content (anything) and render above the backdrop.
+ *
+ * @example Default (bundled image + gradient)
+ * ```tsx
+ * <HeroCard>
+ *   <h2 className="text-3xl font-semibold">Good morning, Maya</h2>
+ * </HeroCard>
+ * ```
+ *
+ * @example Full backdrop control
+ * ```tsx
+ * <HeroCard
+ *   image="/bg/7.webp"
+ *   imageBlur={32}
+ *   imageScale={1.5}
+ *   imageOpacity={0.35}
+ *   imageBlend="overlay"
+ *   imagePosition="top right"
+ *   className="from-rose-500 via-purple-700 to-indigo-900"
+ * >
+ *   …
+ * </HeroCard>
+ * ```
+ */
+export interface HeroCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Backdrop image src. Defaults to the bundled `/bg/3.webp`
+     * (ship the `@flikk/ui/bg/*` assets at `/bg/` or pass your own URL).
+     * Pass `null` for a gradient-only hero.
+     */
+    image?: string | null;
+    /** Backdrop blur radius in px. @default 24 */
+    imageBlur?: number;
+    /** Backdrop scale factor — zooming the abstract blobs in/out reframes the texture. @default 1.25 */
+    imageScale?: number;
+    /** Backdrop opacity, 0–1. @default 0.5 */
+    imageOpacity?: number;
+    /** Blend mode compositing the image over the gradient. @default "multiply" */
+    imageBlend?: HeroCardBlendMode;
+    /** CSS `background-position` — e.g. `"top right"`, `"30% 70%"`. @default "center" */
+    imagePosition?: string;
+    /**
+     * On pointer hover, drift the backdrop image opposite the cursor (damped) for a
+     * parallax-depth effect. Pairs with a `TiltCard` wrapper. Mouse-driven; respects
+     * `prefers-reduced-motion`; no-op without an `image`. Travel is bounded by the
+     * `imageScale` overscan so card edges never show.
+     * @default false
+     */
+    parallax?: boolean;
+    /**
+     * Max backdrop travel in px (each direction) when `parallax` is on. Auto-clamped
+     * to the available `imageScale` overscan.
+     * @default 32
+     */
+    parallaxIntensity?: number;
+    /** className for the content wrapper (the layer lifted above the backdrop). */
+    contentClassName?: string;
+    /** Theme overrides (shadcn approach — `className` still wins). */
+    theme?: HeroCardThemeOverrides;
+}

package/dist/components/core/HeroCard/index.d.ts

@@ -0,0 +1,4 @@
+export { HeroCard, HERO_CARD_DEFAULT_IMAGE } from "./HeroCard";
+export { heroCardTheme } from "./HeroCard.theme";
+export type { HeroCardTheme } from "./HeroCard.theme";
+export type { HeroCardProps, HeroCardThemeOverrides, HeroCardBlendMode } from "./HeroCard.types";

package/dist/components/core/Icon/Icon.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { IconProps } from './Icon.types';
+export declare const Icon: React.ForwardRefExoticComponent<Omit<IconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;

package/dist/components/core/Icon/Icon.js

@@ -0,0 +1,70 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default from 'react';
+import { cn } from '../../../utils/cn.js';
+import { iconTheme } from './Icon.theme.js';
+import { paymentMethods } from './data/paymentMethods.js';
+import { platforms } from './data/platforms.js';
+import { fileTypes } from './data/fileTypes.js';
+
+function renderPaymentIcon(icon, size, colorMode, className, theme, ref, props) {
+    var _a;
+    const method = paymentMethods[icon];
+    const dimensions = typeof size === 'number'
+        ? { width: size, height: Math.round(size * (2 / 3)) }
+        : ((_a = theme.paymentSizes[size]) !== null && _a !== void 0 ? _a : { width: 60, height: 40 });
+    return (jsx("svg", { ref: ref, xmlns: "http://www.w3.org/2000/svg", viewBox: method.viewBox, width: dimensions.width, height: dimensions.height, role: "img", "aria-label": `${method.label} icon`, "data-icon": icon, "data-color-mode": colorMode, "data-size": size, className: cn(theme.baseStyle, className), ...props, children: method.shapes.map((shape, i) => {
+            if (shape.type === 'rect') {
+                const fill = colorMode === 'color' ? shape.fill : 'transparent';
+                const stroke = colorMode === 'color' ? shape.stroke : (shape.stroke ? 'currentColor' : undefined);
+                return (jsx("rect", { x: shape.x, y: shape.y, width: shape.width, height: shape.height, rx: shape.rx, fill: fill, stroke: stroke, strokeWidth: shape.strokeWidth }, i));
+            }
+            return (jsx("path", { d: shape.d, fill: colorMode === 'color' ? shape.fill : 'currentColor', fillRule: shape.fillRule, clipRule: shape.clipRule }, i));
+        }) }));
+}
+function renderSocialIcon(icon, size, colorMode, className, theme, ref, props) {
+    var _a;
+    const platform = platforms[icon];
+    const resolvedSize = typeof size === 'number' ? size : (_a = theme.squareSizes[size]) !== null && _a !== void 0 ? _a : 24;
+    const fill = colorMode === 'color' ? platform.brandColor : 'currentColor';
+    return (jsx("svg", { ref: ref, xmlns: "http://www.w3.org/2000/svg", viewBox: platform.viewBox, width: resolvedSize, height: resolvedSize, fill: fill, role: "img", "aria-label": `${platform.label} icon`, "data-icon": icon, "data-color-mode": colorMode, "data-size": size, className: cn(theme.baseStyle, className), ...props, children: platform.shapes.map((shape, i) => {
+            var _a;
+            return (jsx("path", { d: shape.d, fill: colorMode === 'color' ? ((_a = shape.fill) !== null && _a !== void 0 ? _a : undefined) : undefined }, i));
+        }) }));
+}
+function renderFileTypeIcon(icon, size, colorMode, className, theme, ref, props) {
+    var _a;
+    const fileType = fileTypes[icon];
+    const resolvedSize = typeof size === 'number' ? size : (_a = theme.squareSizes[size]) !== null && _a !== void 0 ? _a : 24;
+    const strokeColor = colorMode === 'color' ? '#D5D7DA' : 'currentColor';
+    const strokeOpacity = colorMode === 'color' ? 1 : 0.3;
+    const badgeColor = colorMode === 'color' ? fileType.color : 'currentColor';
+    const labelText = fileType.label;
+    const badgeWidth = Math.round(labelText.length * 6 + 8);
+    const badgeX = 1;
+    const textX = badgeX + badgeWidth / 2;
+    return (jsxs("svg", { ref: ref, xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 40 40", width: resolvedSize, height: resolvedSize, fill: "none", role: "img", "aria-label": `${fileType.label} file`, "data-icon": icon, "data-color-mode": colorMode, "data-size": size, className: cn(theme.baseStyle, className), ...props, children: [jsx("path", { d: "M11 0.75H27C27.1212 0.75 27.2375 0.798088 27.3232 0.883789L38.1162 11.6768C38.2019 11.7625 38.25 11.8788 38.25 12V36C38.25 37.7949 36.7949 39.25 35 39.25H11C9.20507 39.25 7.75 37.7949 7.75 36V4C7.75 2.20507 9.20508 0.75 11 0.75Z", stroke: strokeColor, strokeWidth: "1.5", opacity: strokeOpacity }), jsx("path", { d: "M27 0.5V8C27 10.2091 28.7909 12 31 12H38.5", stroke: strokeColor, strokeWidth: "1.5", opacity: strokeOpacity }), jsx("rect", { x: badgeX, y: 18, width: badgeWidth, height: 16, rx: 2, fill: badgeColor, opacity: colorMode === 'color' ? 1 : 0.15 }), jsx("text", { x: textX, y: 26, textAnchor: "middle", dominantBaseline: "central", fill: colorMode === 'color' ? 'white' : 'currentColor', fontSize: 9.5, fontWeight: 700, fontFamily: "Arial, Helvetica, sans-serif", letterSpacing: 0.3, children: labelText })] }));
+}
+const Icon = React__default.forwardRef(({ icon, size = 'md', colorMode = 'color', className, theme: customTheme, ...props }, ref) => {
+    const theme = {
+        ...iconTheme,
+        ...customTheme,
+        paymentSizes: { ...iconTheme.paymentSizes, ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.paymentSizes },
+        squareSizes: { ...iconTheme.squareSizes, ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.squareSizes },
+    };
+    if (icon in paymentMethods) {
+        return renderPaymentIcon(icon, size, colorMode, className, theme, ref, props);
+    }
+    if (icon in platforms) {
+        return renderSocialIcon(icon, size, colorMode, className, theme, ref, props);
+    }
+    if (icon in fileTypes) {
+        return renderFileTypeIcon(icon, size, colorMode, className, theme, ref, props);
+    }
+    if (process.env.NODE_ENV !== 'production') {
+        console.warn(`[Icon]: Unknown icon "${icon}".`);
+    }
+    return null;
+});
+Icon.displayName = 'Icon';
+
+export { Icon };

package/dist/components/core/Icon/Icon.theme.d.ts

@@ -0,0 +1,2 @@
+import { IconTheme } from './Icon.types';
+export declare const iconTheme: IconTheme;

package/dist/components/core/Icon/Icon.theme.js

@@ -0,0 +1,19 @@
+const iconTheme = {
+    baseStyle: 'inline-block shrink-0',
+    paymentSizes: {
+        xs: { width: 36, height: 24 },
+        sm: { width: 48, height: 32 },
+        md: { width: 60, height: 40 },
+        lg: { width: 90, height: 60 },
+        xl: { width: 120, height: 80 },
+    },
+    squareSizes: {
+        xs: 16,
+        sm: 20,
+        md: 24,
+        lg: 32,
+        xl: 40,
+    },
+};
+
+export { iconTheme };

package/dist/components/core/Icon/Icon.types.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+export type PaymentIconName = 'visa' | 'mastercard' | 'amex' | 'applepay' | 'paypal';
+export type SocialIconName = 'github' | 'x' | 'linkedin' | 'instagram' | 'facebook' | 'youtube' | 'discord' | 'dribbble' | 'tiktok' | 'reddit' | 'twitch' | 'slack' | 'medium' | 'pinterest' | 'snapchat' | 'whatsapp' | 'telegram' | 'google' | 'apple';
+export type FileTypeName = 'pdf' | 'doc' | 'docx' | 'txt' | 'xls' | 'xlsx' | 'csv' | 'ppt' | 'mp3' | 'wav' | 'mp4' | 'mov' | 'jpg' | 'png' | 'svg' | 'gif' | 'zip' | 'rar';
+export type IconName = PaymentIconName | SocialIconName | FileTypeName;
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** 'color' — uses brand/category colors. 'mono' — uses currentColor. */
+export type IconColorMode = 'color' | 'mono';
+export interface IconDimensions {
+    width: number;
+    height: number;
+}
+export interface IconTheme {
+    baseStyle: string;
+    /** Non-square dimensions for payment icons */
+    paymentSizes: Record<IconSize, IconDimensions>;
+    /** Square size (single number) for social and file-type icons */
+    squareSizes: Record<IconSize, number>;
+}
+export interface IconThemeOverrides {
+    baseStyle?: string;
+    paymentSizes?: Partial<Record<IconSize, IconDimensions>>;
+    squareSizes?: Partial<Record<IconSize, number>>;
+}
+export interface IconProps extends React.SVGProps<SVGSVGElement> {
+    icon: IconName;
+    /** Named size preset or custom pixel value. Payment icons scale at 3:2 ratio; others are square. */
+    size?: IconSize | number;
+    colorMode?: IconColorMode;
+    className?: string;
+    theme?: IconThemeOverrides;
+}

package/dist/components/core/Icon/data/fileTypes.d.ts

@@ -0,0 +1,7 @@
+import { FileTypeName } from '../Icon.types';
+export interface FileTypeData {
+    label: string;
+    color: string;
+    category: string;
+}
+export declare const fileTypes: Record<FileTypeName, FileTypeData>;

package/dist/components/core/Icon/data/fileTypes.js

@@ -0,0 +1,30 @@
+const fileTypes = {
+    // PDF
+    pdf: { label: 'PDF', color: '#E5252A', category: 'pdf' },
+    // Documents
+    doc: { label: 'DOC', color: '#2B7CD3', category: 'document' },
+    docx: { label: 'DOCX', color: '#2B7CD3', category: 'document' },
+    txt: { label: 'TXT', color: '#4B5563', category: 'document' },
+    // Spreadsheets
+    xls: { label: 'XLS', color: '#1D6F42', category: 'spreadsheet' },
+    xlsx: { label: 'XLSX', color: '#1D6F42', category: 'spreadsheet' },
+    csv: { label: 'CSV', color: '#1D6F42', category: 'spreadsheet' },
+    // Presentations
+    ppt: { label: 'PPT', color: '#D04423', category: 'presentation' },
+    // Audio
+    mp3: { label: 'MP3', color: '#8B5CF6', category: 'audio' },
+    wav: { label: 'WAV', color: '#8B5CF6', category: 'audio' },
+    // Video
+    mp4: { label: 'MP4', color: '#7C3AED', category: 'video' },
+    mov: { label: 'MOV', color: '#7C3AED', category: 'video' },
+    // Images
+    jpg: { label: 'JPG', color: '#F59E0B', category: 'image' },
+    png: { label: 'PNG', color: '#F59E0B', category: 'image' },
+    svg: { label: 'SVG', color: '#F59E0B', category: 'image' },
+    gif: { label: 'GIF', color: '#F59E0B', category: 'image' },
+    // Archives
+    zip: { label: 'ZIP', color: '#CA8A04', category: 'archive' },
+    rar: { label: 'RAR', color: '#CA8A04', category: 'archive' },
+};
+
+export { fileTypes };

package/dist/components/core/Icon/data/paymentMethods.d.ts

@@ -0,0 +1,27 @@
+import { PaymentIconName } from '../Icon.types';
+type ShapeRect = {
+    type: 'rect';
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+    rx?: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+};
+type ShapePath = {
+    type: 'path';
+    d: string;
+    fill?: string;
+    fillRule?: 'evenodd' | 'nonzero';
+    clipRule?: 'evenodd' | 'nonzero';
+};
+export type PaymentShape = ShapeRect | ShapePath;
+export interface PaymentMethodData {
+    viewBox: string;
+    label: string;
+    shapes: PaymentShape[];
+}
+export declare const paymentMethods: Record<PaymentIconName, PaymentMethodData>;
+export {};