@flikk/ui 1.0.0-beta.29 → 1.0.0-beta.30

package/dist/utils/actionQueue.d.ts

@@ -1,7 +1,3 @@
-/**
- * Action Queue for Offline Support
- * Manages queued mutations when the user is offline
- */
 /**
  * Queued action interface
  */

package/dist/utils/actionQueue.js

@@ -1,9 +1,6 @@
+"use client";
 import { QueueError } from './optimisticErrors.js';
 
-/**
- * Action Queue for Offline Support
- * Manages queued mutations when the user is offline
- */
 /**
  * ActionQueue class for managing offline mutations
  */

package/dist/utils/cn.js

@@ -1,6 +1,26 @@
 import { clsx } from 'clsx';
-import { twMerge } from 'tailwind-merge';
+import { extendTailwindMerge } from 'tailwind-merge';
 
+// Teach tailwind-merge about our custom box-shadow utilities (defined as `@utility` in
+// global.scss). Without this they are unknown to twMerge, so a consumer's `className="shadow-none"`
+// (or `shadow-lg`) would NOT cancel an engine-applied `shadow-surface-5` / `shadow-real-xl` — both
+// classes survive and CSS source order decides, silently breaking the "className wins" contract.
+// Registering them in the standard `shadow` (box-shadow) group makes them mutually exclusive with
+// each other and with the core shadow utilities, so the last/override class wins as expected.
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            shadow: [
+                'shadow-real-sm', 'shadow-real-md', 'shadow-real-lg',
+                'shadow-real-xl', 'shadow-real-2xl', 'shadow-real-3xl',
+                'shadow-inner-real-sm', 'shadow-inner-real-md', 'shadow-inner-real-lg',
+                'shadow-inner-real-xl', 'shadow-inner-real-2xl', 'shadow-inner-real-3xl',
+                'shadow-surface-1', 'shadow-surface-2', 'shadow-surface-3', 'shadow-surface-4',
+                'shadow-surface-5', 'shadow-surface-6', 'shadow-surface-7', 'shadow-surface-8',
+            ],
+        },
+    },
+});
 function cn(...inputs) {
     return twMerge(clsx(inputs));
 }

package/dist/utils/colorUtils.d.ts

@@ -4,7 +4,7 @@
  * Components with extra colors extend locally:
  *   export type SpinnerColor = SemanticColor | 'dark';
  */
-export type SemanticColor = "neutral" | "primary" | "secondary" | "success" | "warning" | "danger";
+export type SemanticColor = "neutral" | "primary" | "success" | "warning" | "danger";
 /**
  * Background colors for semantic colors.
  * neutral uses neutral-400; others use their base variable.
@@ -21,3 +21,33 @@ export declare const semanticTextColors: Record<SemanticColor, string>;
  * neutral uses --color-border; others use their base variable.
  */
 export declare const semanticSpinnerColors: Record<SemanticColor, string>;
+/** Which text tone reads best on a given background. */
+export type ContrastTone = "light" | "dark";
+/** Parse a `#rgb` or `#rrggbb` string to 0–255 channels. Returns null otherwise. */
+export declare const hexToRgb: (hex: string) => {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * WCAG relative luminance of a color, 0 (black) → 1 (white). Non-hex inputs
+ * (CSS variables, named colors) can't be measured at runtime, so they return a
+ * neutral `0.5` rather than throwing.
+ */
+export declare const relativeLuminance: (color: string) => number;
+/**
+ * Choose the text tone (`"light"` | `"dark"`) for a background. Pass an array of
+ * colors (e.g. a gradient's colors) to decide from their average luminance.
+ *
+ * `threshold` (0–1, default `0.179` — the WCAG black/white crossover) is the
+ * luminance at/above which the background counts as "bright" → dark text. Raise
+ * it to favor **light** text on more mid-tone backgrounds; lower it for the
+ * reverse.
+ *
+ * Returns a theme-agnostic tone — map it to your colors at the call site, e.g.
+ * `tone === "dark" ? "var(--color-neutral-950)" : "var(--color-neutral-50)"`
+ * (the neutral scale is theme-stable, so the decision holds in light and dark).
+ */
+export declare const contrastTone: (bg: string | string[], options?: {
+    threshold?: number;
+}) => ContrastTone;

package/dist/utils/colorUtils.js

@@ -11,7 +11,6 @@
 const semanticBgColors = {
     neutral: "bg-[var(--color-neutral-400)]",
     primary: "bg-[var(--color-primary)]",
-    secondary: "bg-[var(--color-secondary)]",
     success: "bg-[var(--color-success)]",
     warning: "bg-[var(--color-warning)]",
     danger: "bg-[var(--color-danger)]",
@@ -23,7 +22,6 @@ const semanticBgColors = {
 const semanticTextColors = {
     neutral: "text-[var(--color-text-primary)]",
     primary: "text-[var(--color-primary)]",
-    secondary: "text-[var(--color-secondary)]",
     success: "text-[var(--color-success)]",
     warning: "text-[var(--color-warning)]",
     danger: "text-[var(--color-danger)]",
@@ -36,10 +34,57 @@ const semanticTextColors = {
 const semanticSpinnerColors = {
     neutral: "border-[var(--color-border)] border-t-transparent",
     primary: "border-[var(--color-primary)] border-t-transparent",
-    secondary: "border-[var(--color-secondary)] border-t-transparent",
     success: "border-[var(--color-success)] border-t-transparent",
     warning: "border-[var(--color-warning)] border-t-transparent",
     danger: "border-[var(--color-danger)] border-t-transparent",
 };
+/** Parse a `#rgb` or `#rrggbb` string to 0–255 channels. Returns null otherwise. */
+const hexToRgb = (hex) => {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    let h = m[1];
+    if (h.length === 3) {
+        h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    }
+    const n = parseInt(h, 16);
+    return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+};
+/**
+ * WCAG relative luminance of a color, 0 (black) → 1 (white). Non-hex inputs
+ * (CSS variables, named colors) can't be measured at runtime, so they return a
+ * neutral `0.5` rather than throwing.
+ */
+const relativeLuminance = (color) => {
+    const rgb = hexToRgb(color);
+    if (!rgb)
+        return 0.5;
+    const channel = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return (0.2126 * channel(rgb.r) + 0.7152 * channel(rgb.g) + 0.0722 * channel(rgb.b));
+};
+/**
+ * Choose the text tone (`"light"` | `"dark"`) for a background. Pass an array of
+ * colors (e.g. a gradient's colors) to decide from their average luminance.
+ *
+ * `threshold` (0–1, default `0.179` — the WCAG black/white crossover) is the
+ * luminance at/above which the background counts as "bright" → dark text. Raise
+ * it to favor **light** text on more mid-tone backgrounds; lower it for the
+ * reverse.
+ *
+ * Returns a theme-agnostic tone — map it to your colors at the call site, e.g.
+ * `tone === "dark" ? "var(--color-neutral-950)" : "var(--color-neutral-50)"`
+ * (the neutral scale is theme-stable, so the decision holds in light and dark).
+ */
+const contrastTone = (bg, options = {}) => {
+    const { threshold = 0.179 } = options;
+    const colors = Array.isArray(bg) ? bg : [bg];
+    const luminance = colors.length
+        ? colors.reduce((sum, c) => sum + relativeLuminance(c), 0) / colors.length
+        : 0.5;
+    return luminance >= threshold ? "dark" : "light";
+};
 
-export { semanticBgColors, semanticSpinnerColors, semanticTextColors };
+export { contrastTone, hexToRgb, relativeLuminance, semanticBgColors, semanticSpinnerColors, semanticTextColors };

package/dist/utils/dateUtils.js

@@ -68,22 +68,27 @@ const formatDateCustom = (date, formatString, locale = 'en-US') => {
     // Get month names based on locale
     const shortMonths = Array.from({ length: 12 }, (_, i) => new Date(2000, i, 1).toLocaleDateString(locale, { month: 'short' }));
     const fullMonths = Array.from({ length: 12 }, (_, i) => new Date(2000, i, 1).toLocaleDateString(locale, { month: 'long' }));
-    // Replace tokens in order of length (longest first to avoid conflicts)
-    let result = formatString;
-    // Year tokens
-    result = result.replace(/YYYY/g, year.toString());
-    result = result.replace(/YY/g, year.toString().slice(-2));
-    // Month tokens (longest first) — use \x00-wrapped placeholders to prevent collisions
-    result = result.replace(/MMMM/g, `\x00${fullMonths[month - 1]}\x00`);
-    result = result.replace(/MMM/g, `\x00${shortMonths[month - 1]}\x00`);
-    result = result.replace(/MM/g, month.toString().padStart(2, '0'));
-    result = result.replace(/M/g, month.toString());
-    // Day tokens (longest first)
-    result = result.replace(/DD/g, day.toString().padStart(2, '0'));
-    result = result.replace(/D/g, day.toString());
-    // Strip placeholders
-    result = result.replace(/\x00/g, '');
-    return result;
+    // Tokenize in a SINGLE pass: a sequential series of global .replace() calls
+    // (one per token) re-scans the ENTIRE string on every pass, including text
+    // that a previous pass just substituted in — so a month name that itself
+    // contains a token letter gets mangled (e.g. "MMM" -> "Mar", then a later
+    // `/M/g` pass matches the "M" inside "Mar" too, producing "3ar"; "May"
+    // similarly becomes "3ay"). A single regex + replacer callback matches each
+    // token exactly once against the ORIGINAL format string, so substituted
+    // text is never re-matched.
+    const tokenValues = {
+        YYYY: year.toString(),
+        YY: year.toString().slice(-2),
+        MMMM: fullMonths[month - 1],
+        MMM: shortMonths[month - 1],
+        MM: month.toString().padStart(2, '0'),
+        M: month.toString(),
+        DD: day.toString().padStart(2, '0'),
+        D: day.toString(),
+    };
+    // Longest-token-first alternation so e.g. "MMMM" matches before "MM"/"M".
+    const tokenRegex = /YYYY|YY|MMMM|MMM|MM|M|DD|D/g;
+    return formatString.replace(tokenRegex, (token) => { var _a; return (_a = tokenValues[token]) !== null && _a !== void 0 ? _a : token; });
 };
 /**
  * Get date range for this week (Monday to Sunday)

package/dist/utils/index.d.ts

@@ -12,6 +12,6 @@ export * from "./stateMachine";
 export * from "./formValidation";
 export { calculateVelocity, clampScroll, detectScrollDirection, isReducedMotion, lerp, calculateScrollProgress, normalizeWheelDelta, isScrollable, getMaxScroll, throttle, } from './smoothScrollUtils';
 export { PerformanceMonitor, usePerformanceMonitor } from './performanceMonitor';
-export { type SemanticColor, semanticBgColors, semanticTextColors, semanticSpinnerColors, } from './colorUtils';
+export { type SemanticColor, type ContrastTone, semanticBgColors, semanticTextColors, semanticSpinnerColors, hexToRgb, relativeLuminance, contrastTone, } from './colorUtils';
 export { formatFileSize, getFileExtension } from './formatUtils';
 export { generatePalette, generateThemeCSS, type PaletteStep, type GeneratedPalette, type GeneratePaletteOptions, } from './paletteGenerator';

package/dist/utils/performanceMonitor.js

@@ -1,3 +1,4 @@
+"use client";
 import 'react';
 
 /**

package/dist/utils/smoothScrollUtils.js

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Calculate velocity from position change
  *

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@flikk/ui",
-  "version": "1.0.0-beta.29",
+  "version": "1.0.0-beta.30",
   "description": "A modern React component library built with TypeScript, Tailwind CSS v4, and Framer Motion. Follows the shadcn philosophy with complete className override support.",
   "type": "module",
+  "packageManager": "yarn@1.22.22",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -70,21 +71,25 @@
     "./registry.json": "./dist/registry.json",
     "./generative.schema.json": "./dist/generative.schema.json",
     "./tools.json": "./dist/tools.json",
+    "./CHANGELOG.md": "./CHANGELOG.md",
     "./bg/*": "./dist/bg/*"
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "LICENSE",
     "tailwind.preset.cjs",
     "src/global.scss",
     "src/styles"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "rollup -c && npm run build:css && npm run build:assets && npm run build:copy-css && npm run build:registry && npm run build:generative",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "node scripts/audit-use-client.mjs && rollup -c && npm run build:css && npm run build:assets && npm run build:copy-css && npm run build:registry && npm run build:generative",
     "build:assets": "cp -r public/bg dist/bg",
     "build:registry": "FLIKK_REGISTRY_OUT=dist/registry.json packages/mcp/node_modules/.bin/tsx packages/mcp/scripts/extract.ts",
     "build:generative": "packages/mcp/node_modules/.bin/tsx packages/mcp/scripts/generative.ts",
+    "build:inventory": "packages/mcp/node_modules/.bin/tsx packages/mcp/scripts/generateInventory.ts",
     "build:copy-css": "cp src/shadcn-compat.css dist/shadcn-compat.css && cp src/theme-plugin.css dist/theme.css",
     "build:css": "tailwindcss -m -i ./src/tailwind-config.css -o ./dist/styles.css",
     "analyze": "ANALYZE=true rollup -c && open stats.html",
@@ -92,7 +97,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
     "clean": "rimraf dist",
-    "prepublishOnly": "npm run clean && npm run build",
+    "prepublishOnly": "npm run clean && npm run test && npm run build",
     "dev": "concurrently \"npm run watch:css:dev\" \"storybook dev -p 6006\" \"npm --prefix apps/docs run dev\"",
     "storybook": "concurrently \"npm run watch:css:dev\" \"storybook dev -p 6006\"",
     "watch:css:dev": "tailwindcss --watch -i ./src/tailwind-config.css -o ./src/index.css",
@@ -161,6 +166,7 @@
   "devDependencies": {
     "@chromatic-com/storybook": "^5.0.0",
     "@emotion/is-prop-valid": "^1.4.0",
+    "@eslint/js": "^9",
     "@heroicons/react": "^2.2.0",
     "@react-three/drei": "^10.7.7",
     "@react-three/fiber": "^9.5.0",
@@ -176,15 +182,25 @@
     "@storybook/addon-webpack5-compiler-swc": "^4.0.2",
     "@storybook/react-webpack5": "^10.2.3",
     "@tailwindcss/cli": "^4.1.18",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest-axe": "^3.5.9",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.11",
     "@types/three": "^0.182.0",
+    "@vitejs/plugin-react": "^5.2.0",
     "autoprefixer": "^10.4.24",
     "concurrently": "^9.2.1",
+    "eslint": "^9",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-storybook": "^10.2.7",
+    "globals": "^17.7.0",
     "gsap": "^3.14.2",
+    "jest-axe": "^10.0.0",
+    "jsdom": "^29.1.1",
     "motion": "^12.19.1",
     "postcss": "^8.5.3",
     "react": "^19.2.4",
@@ -194,12 +210,14 @@
     "remark-gfm": "^4.0.1",
     "rimraf": "^5.0.0",
     "rollup": "^4.57.1",
+    "rollup-plugin-preserve-directives": "^0.4.0",
     "rollup-plugin-visualizer": "^7.0.1",
     "storybook": "^10.2.3",
     "three": "^0.182.0",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.61.0"
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^3.2.6"
   },
   "dependencies": {
     "clsx": "^2.1.1",

package/src/global.scss

@@ -361,6 +361,19 @@
 @utility shadow-real-2xl { box-shadow: var(--elevation-real-2xl); }
 @utility shadow-real-3xl { box-shadow: var(--elevation-real-3xl); }
 
+/* Per-rung elevation shadows for the relative-elevation engine (src/theme/SurfaceContext).
+   shadow-surface-N pairs with bg-[var(--surface-N)] so a nested surface gets BOTH the lighter
+   rung (dark) and the deeper shadow (light) at the same level. Same --elevation-* (not --shadow-*)
+   naming + single-class specificity as shadow-real-*, so shadow-none still cancels them. */
+@utility shadow-surface-1 { box-shadow: var(--elevation-surface-1); }
+@utility shadow-surface-2 { box-shadow: var(--elevation-surface-2); }
+@utility shadow-surface-3 { box-shadow: var(--elevation-surface-3); }
+@utility shadow-surface-4 { box-shadow: var(--elevation-surface-4); }
+@utility shadow-surface-5 { box-shadow: var(--elevation-surface-5); }
+@utility shadow-surface-6 { box-shadow: var(--elevation-surface-6); }
+@utility shadow-surface-7 { box-shadow: var(--elevation-surface-7); }
+@utility shadow-surface-8 { box-shadow: var(--elevation-surface-8); }
+
 /* Inset counterparts — recessed/sunken surfaces (input wells, code blocks, sunken
    panels, pressed states). Light: top-down "well" (X zeroed, rim-hugging negative
    spreads). Dark: stronger black inset + a 1px bottom-inner white lip. */
@@ -910,6 +923,80 @@ body {
   }
 }
 
+/* ---------------------------------------------------------------------------
+   Shimmer effect (effects/Shimmer) — the "AI thinking" text shimmer + a
+   surface sweep for loading placeholders. Pure CSS, GPU-friendly. Tokens
+   (--shimmer-*) and their .dark overrides live in styles/theme.css @layer theme.
+   Distinct keyframe names from the `shimmer` loader above (left untouched).
+--------------------------------------------------------------------------- */
+@keyframes shimmer-text {
+  to {
+    background-position: -200% center;
+  }
+}
+
+@keyframes shimmer-sweep {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(100%);
+  }
+}
+
+/* Text shimmer: muted glyphs with a brighter highlight band sweeping across,
+   via background-clip:text + animated background-position. */
+.flikk-shimmer-text {
+  background: linear-gradient(
+    90deg,
+    var(--shimmer-color) 0%,
+    var(--shimmer-color) calc(50% - var(--shimmer-spread)),
+    var(--shimmer-highlight) 50%,
+    var(--shimmer-color) calc(50% + var(--shimmer-spread)),
+    var(--shimmer-color) 100%
+  );
+  background-size: 200% auto;
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+  animation: shimmer-text var(--shimmer-duration) linear infinite;
+}
+
+/* Surface sweep: a highlight band travels across any box. The consumer supplies
+   the placeholder background via className; the sweep rides on a ::after layer. */
+.flikk-shimmer-surface {
+  position: relative;
+  overflow: hidden;
+}
+
+.flikk-shimmer-surface::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    var(--shimmer-surface-highlight) 50%,
+    transparent 100%
+  );
+  animation: shimmer-sweep var(--shimmer-duration) linear infinite;
+}
+
+/* Accessibility: cancel motion and render text in a plain, readable base color. */
+@media (prefers-reduced-motion: reduce) {
+  .flikk-shimmer-text {
+    animation: none;
+    background: none;
+    color: var(--shimmer-color);
+    -webkit-text-fill-color: currentColor;
+  }
+
+  .flikk-shimmer-surface::after {
+    animation: none;
+  }
+}
+
 /* Progress bar indeterminate animation */
 @keyframes progress-indeterminate {
   0% {