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

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

@@ -0,0 +1,53 @@
+/**
+ * Shared semantic color type and common color maps.
+ *
+ * Components with extra colors extend locally:
+ *   export type SpinnerColor = SemanticColor | 'dark';
+ */
+export type SemanticColor = "mono" | "primary" | "success" | "warning" | "danger";
+/**
+ * Background colors for semantic colors.
+ * mono (the gray role) uses mono-400; others use their base variable.
+ */
+export declare const semanticBgColors: Record<SemanticColor, string>;
+/**
+ * Text colors for semantic colors.
+ * mono uses text-primary; others use their base variable.
+ */
+export declare const semanticTextColors: Record<SemanticColor, string>;
+/**
+ * Spinner border colors for semantic colors.
+ * Each value is the atomic pair: border color + transparent top.
+ * mono 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-mono-950)" : "var(--color-mono-50)"`
+ * (the mono 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

@@ -0,0 +1,90 @@
+/**
+ * Shared semantic color type and common color maps.
+ *
+ * Components with extra colors extend locally:
+ *   export type SpinnerColor = SemanticColor | 'dark';
+ */
+/**
+ * Background colors for semantic colors.
+ * mono (the gray role) uses mono-400; others use their base variable.
+ */
+const semanticBgColors = {
+    mono: "bg-[var(--color-mono-400)]",
+    primary: "bg-[var(--color-primary)]",
+    success: "bg-[var(--color-success)]",
+    warning: "bg-[var(--color-warning)]",
+    danger: "bg-[var(--color-danger)]",
+};
+/**
+ * Text colors for semantic colors.
+ * mono uses text-primary; others use their base variable.
+ */
+const semanticTextColors = {
+    mono: "text-[var(--color-text-primary)]",
+    primary: "text-[var(--color-primary)]",
+    success: "text-[var(--color-success)]",
+    warning: "text-[var(--color-warning)]",
+    danger: "text-[var(--color-danger)]",
+};
+/**
+ * Spinner border colors for semantic colors.
+ * Each value is the atomic pair: border color + transparent top.
+ * mono uses --color-border; others use their base variable.
+ */
+const semanticSpinnerColors = {
+    mono: "border-[var(--color-border)] border-t-transparent",
+    primary: "border-[var(--color-primary)] 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-mono-950)" : "var(--color-mono-50)"`
+ * (the mono 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 { contrastTone, hexToRgb, relativeLuminance, semanticBgColors, semanticSpinnerColors, semanticTextColors };

package/dist/utils/dateUtils.js

@@ -68,20 +68,76 @@ 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 (MMMM before MMM before MM before M)
-    result = result.replace(/MMMM/g, fullMonths[month - 1]);
-    result = result.replace(/MMM/g, shortMonths[month - 1]);
-    result = result.replace(/MM/g, month.toString().padStart(2, '0'));
-    result = result.replace(/M/g, month.toString());
-    // Day tokens (DD before D)
-    result = result.replace(/DD/g, day.toString().padStart(2, '0'));
-    result = result.replace(/D/g, day.toString());
-    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)
+ */
+const getThisWeek = () => {
+    const now = new Date();
+    const dayOfWeek = now.getDay();
+    const mondayOffset = dayOfWeek === 0 ? -6 : 1 - dayOfWeek;
+    const start = new Date(now);
+    start.setDate(now.getDate() + mondayOffset);
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(start);
+    end.setDate(start.getDate() + 6);
+    end.setHours(23, 59, 59, 999);
+    return { start, end };
+};
+/**
+ * Get date range for last week (Monday to Sunday)
+ */
+const getLastWeek = () => {
+    const thisWeek = getThisWeek();
+    const start = new Date(thisWeek.start);
+    start.setDate(start.getDate() - 7);
+    const end = new Date(thisWeek.start);
+    end.setDate(end.getDate() - 1);
+    end.setHours(23, 59, 59, 999);
+    return { start, end };
+};
+/**
+ * Get date range for this month
+ */
+const getThisMonth = () => {
+    const now = new Date();
+    const start = new Date(now.getFullYear(), now.getMonth(), 1);
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(now.getFullYear(), now.getMonth() + 1, 0);
+    end.setHours(23, 59, 59, 999);
+    return { start, end };
+};
+/**
+ * Get date range for last month
+ */
+const getLastMonth = () => {
+    const now = new Date();
+    const start = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(now.getFullYear(), now.getMonth(), 0);
+    end.setHours(23, 59, 59, 999);
+    return { start, end };
 };
 // ---------------------------------------------------------------------------
 // Generic date utilities (shared across components)
@@ -140,5 +196,15 @@ function getDaysBetween(a, b) {
     const end = toDate(b);
     return Math.round((end.getTime() - start.getTime()) / 86400000) + 1;
 }
+/**
+ * Get the ISO week number for a date.
+ */
+function getWeekNumber(date) {
+    const d = new Date(date);
+    d.setHours(0, 0, 0, 0);
+    d.setDate(d.getDate() + 3 - ((d.getDay() + 6) % 7));
+    const yearStart = new Date(d.getFullYear(), 0, 1);
+    return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+}
 
-export { addDays, formatDateCustom, formatTimestamp, getDaysBetween, isSameDay, isWeekend, toDate };
+export { addDays, formatDateCustom, formatTimestamp, getDaysBetween, getLastMonth, getLastWeek, getThisMonth, getThisWeek, getWeekNumber, isSameDay, isWeekend, toDate };

package/dist/utils/formatUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Format a byte count into a human-readable file size string.
+ * Uses binary units (1 KB = 1024 bytes).
+ */
+export declare const formatFileSize: (bytes: number) => string;
+/**
+ * Extract the file extension from a filename, lowercase.
+ * Returns null if no extension is present.
+ */
+export declare const getFileExtension: (filename: string) => string | null;

package/dist/utils/formatUtils.js

@@ -0,0 +1,24 @@
+/**
+ * Format a byte count into a human-readable file size string.
+ * Uses binary units (1 KB = 1024 bytes).
+ */
+const formatFileSize = (bytes) => {
+    if (bytes === 0)
+        return "0 Bytes";
+    const k = 1024;
+    const sizes = ["Bytes", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + " " + sizes[i];
+};
+/**
+ * Extract the file extension from a filename, lowercase.
+ * Returns null if no extension is present.
+ */
+const getFileExtension = (filename) => {
+    const dotIndex = filename.lastIndexOf(".");
+    if (dotIndex === -1 || dotIndex === filename.length - 1)
+        return null;
+    return filename.slice(dotIndex + 1).toLowerCase();
+};
+
+export { formatFileSize, getFileExtension };

package/dist/utils/index.d.ts

@@ -1,7 +1,6 @@
 export { cn } from "./cn";
 export { debounce } from "./debounce";
 export { formatTimestamp, formatDate, formatTime, formatDateCustom, formatRelativeTime, isToday, isYesterday, isThisWeek, getLastNDays, getThisWeek, getLastWeek, getThisMonth, getLastMonth, getThisYear, getLastYear, toDate, addDays, isSameDay, isWeekend, getDaysBetween, getWeekNumber, type DateInput, type TimestampOptions, type DateRange, } from "./dateUtils";
-export { useClickOutside } from "./useClickOutside";
 export { findNextMatchingOption, isValidTypeaheadChar, TYPEAHEAD_TIMEOUT_MS, type TypeaheadOption, type FindNextMatchingOptionParams, } from "./typeaheadUtils";
 export { timeToMinutes, minutesToTime, getEventDuration, getTotalTimeSlots, getTimeSlotIndex, getTimeSlotForIndex, calculateEventPosition, calculateEventHeight, eventsOverlap, findOverlappingEvents, groupOverlappingEvents, resolveOverlappingEvents, generateTimeGrid, filterEventsByDate, sortEventsByStartTime, separateAllDayEvents, isValidTimeFormat, isValidDateFormat, validateEvent, DEFAULT_GRID_CONFIGS, type CalendarEvent, type GridConfig, type EventPosition, type EventLayout, type TimeSlot, } from "./calendarUtils";
 export { parseOpenAI, parseAnthropic, parseGemini, parseSSELine, SSE_PARSERS, type SSEFormat, type SSEParser, } from "./sseFormatParsers";
@@ -13,3 +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, 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/paletteGenerator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Palette Generator Utility
+ *
+ * Converts a hex color to an 11-step OKLCH palette using
+ * Tailwind-matched lightness/chroma curves. The hue is extracted
+ * from the input color and applied across all steps.
+ */
+export interface PaletteStep {
+    /** Tailwind step number: 50, 100, 200 ... 950 */
+    step: number;
+    /** OKLCH CSS string, e.g. "oklch(0.9778 0.0108 270)" */
+    oklch: string;
+    /** Approximate sRGB hex for preview swatches */
+    hex: string;
+}
+export interface GeneratedPalette {
+    /** Semantic name, e.g. "primary" */
+    name: string;
+    /** Extracted OKLCH hue (degrees) */
+    hue: number;
+    /** 11 palette steps from 50 to 950 */
+    steps: PaletteStep[];
+    /** Auto-calculated contrast color (hex) for text on the base step */
+    contrast: 'light' | 'dark';
+}
+export interface GeneratePaletteOptions {
+    /** Scales chroma up/down. Default 1.0 */
+    vibrancy?: number;
+}
+/**
+ * Generate an 11-step OKLCH palette from a single hex color.
+ * Extracts the hue from the input and applies Tailwind-matched
+ * lightness and chroma curves.
+ */
+export declare function generatePalette(hex: string, name?: string, options?: GeneratePaletteOptions): GeneratedPalette | null;
+/**
+ * Generate a complete CSS variable block for all semantic colors.
+ *
+ * @param palettes - Map of semantic name → hex color
+ * @param options - Generation options (vibrancy)
+ * @returns Object with `theme` (for @theme block) and `root` (for :root block) CSS strings
+ */
+export declare function generateThemeCSS(palettes: Record<string, string>, options?: GeneratePaletteOptions): {
+    theme: string;
+    root: string;
+} | null;

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/dist/utils/stateMachine.d.ts

@@ -3,13 +3,13 @@
  * Lightweight engine for declarative form transitions and branching.
  */
 export type StateIdentifier = string;
-export interface StateMachineConfig<TContext = any> {
+export interface StateMachineConfig<TContext = unknown> {
     /** The initial state name */
     initial: StateIdentifier;
     /** State definitions */
     states: Record<StateIdentifier, StateDefinition<TContext>>;
 }
-export interface StateDefinition<TContext = any> {
+export interface StateDefinition<TContext = unknown> {
     /** Map of events to transitions */
     on?: Record<string, Transition<TContext>>;
     /** Actions executed when entering this state */
@@ -17,8 +17,8 @@ export interface StateDefinition<TContext = any> {
     /** Actions executed when exiting this state */
     exit?: Array<(context: TContext) => void>;
 }
-export type Transition<TContext = any> = StateIdentifier | TransitionConfig<TContext>;
-export interface TransitionConfig<TContext = any> {
+export type Transition<TContext = unknown> = StateIdentifier | TransitionConfig<TContext>;
+export interface TransitionConfig<TContext = unknown> {
     /** Target state */
     target: StateIdentifier;
     /** Optional conditional guard */