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

package/dist/components/forms/RichTextEditor/RichTextEditor.theme.d.ts

@@ -1,8 +1,60 @@
 import { RichTextEditorTheme, ColorOption } from "./RichTextEditor.types";
 /**
- * Color options for text color picker
+ * Legacy 10-entry color list — kept for backwards compat with consumers that
+ * import `colorOptions` directly. The RichTextEditor's color picker now uses
+ * the full Tailwind spectrum below.
  */
 export declare const colorOptions: ColorOption[];
+/**
+ * Tailwind shade scale (same for every family). Used by both the picker
+ * UI and the `getTailwindShadeTokens` utility below.
+ */
+export declare const TAILWIND_SHADE_LABELS: readonly ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"];
+/**
+ * The 22 Tailwind color families, in spectrum order.
+ * Tailwind v4 exposes each shade as `--color-{family}-{shade}` automatically,
+ * so we render swatches via `var(--color-...)` instead of hardcoding hex.
+ */
+export declare const TAILWIND_COLOR_FAMILIES: readonly ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose"];
+/**
+ * Returns shade tokens for a given Tailwind family.
+ *
+ * @example
+ * getTailwindShadeTokens("slate")
+ * // → ["slate-50", "slate-100", "slate-200", ..., "slate-950"]
+ */
+export declare const getTailwindShadeTokens: (family: string) => string[];
+/**
+ * Resolves a Tailwind shade token to a CSS color value usable in inline
+ * styles for swatch backgrounds. Reads `--color-{token}` directly; modern
+ * browsers accept the resulting `oklch(...)` (or fallback `rgb()`) in
+ * `background-color` without normalization.
+ *
+ * SSR-safe: returns `var(--color-{token})` literal when document is absent.
+ */
+export declare const resolveTailwindColor: (token: string) => string;
+/**
+ * Tailwind v4 only emits `--color-{family}-{shade}` CSS vars for shades that
+ * appear as utility classes in source. Since the picker resolves them at
+ * runtime via `var(...)`, we need every shade present. This sentinel string
+ * lists `bg-{family}-{shade}` for the full 22×11 palette so Tailwind's
+ * content scanner emits all CSS variables. Not used at runtime.
+ */
+export declare const _TAILWIND_PALETTE_KEEPALIVE: string;
+/**
+ * The two non-family base colors users always reach for, shown in their own row
+ * above the spectrum.
+ *
+ * `value` is the resolved background color (used to paint the swatch);
+ * `token` is the Tailwind shade fragment used to build the `text-{token}`
+ * class applied to the editor content.
+ */
+export declare const MONO_COLORS: {
+    name: string;
+    value: string;
+    token: string;
+}[];
+export declare const _RTE_CLASSES_KEEPALIVE: string;
 /**
  * Rich Text Editor theme - extends common forms base theme for consistency
  */

package/dist/components/forms/RichTextEditor/RichTextEditor.theme.js

@@ -1,19 +1,88 @@
+"use client";
 import { formsBaseTheme } from '../forms.theme.js';
 
 /**
- * Color options for text color picker
+ * Tailwind shade scale (same for every family). Used by both the picker
+ * UI and the `getTailwindShadeTokens` utility below.
  */
-const colorOptions = [
-    { label: "Black", value: "#000000", className: "text-black" },
-    { label: "Gray", value: "#6B7280", className: "text-gray-500" },
-    { label: "Red", value: "#EF4444", className: "text-red-500" },
-    { label: "Orange", value: "#F97316", className: "text-orange-500" },
-    { label: "Yellow", value: "#EAB308", className: "text-yellow-500" },
-    { label: "Green", value: "#22C55E", className: "text-green-500" },
-    { label: "Blue", value: "#3B82F6", className: "text-blue-500" },
-    { label: "Indigo", value: "#6366F1", className: "text-indigo-500" },
-    { label: "Purple", value: "#A855F7", className: "text-purple-500" },
-    { label: "Pink", value: "#EC4899", className: "text-pink-500" },
+const TAILWIND_SHADE_LABELS = [
+    "50",
+    "100",
+    "200",
+    "300",
+    "400",
+    "500",
+    "600",
+    "700",
+    "800",
+    "900",
+    "950",
+];
+/**
+ * The 22 Tailwind color families, in spectrum order.
+ * Tailwind v4 exposes each shade as `--color-{family}-{shade}` automatically,
+ * so we render swatches via `var(--color-...)` instead of hardcoding hex.
+ */
+const TAILWIND_COLOR_FAMILIES = [
+    "slate",
+    "gray",
+    "zinc",
+    "neutral",
+    "stone",
+    "red",
+    "orange",
+    "amber",
+    "yellow",
+    "lime",
+    "green",
+    "emerald",
+    "teal",
+    "cyan",
+    "sky",
+    "blue",
+    "indigo",
+    "violet",
+    "purple",
+    "fuchsia",
+    "pink",
+    "rose",
+];
+/**
+ * Returns shade tokens for a given Tailwind family.
+ *
+ * @example
+ * getTailwindShadeTokens("slate")
+ * // → ["slate-50", "slate-100", "slate-200", ..., "slate-950"]
+ */
+const getTailwindShadeTokens = (family) => TAILWIND_SHADE_LABELS.map((shade) => `${family}-${shade}`);
+/**
+ * Resolves a Tailwind shade token to a CSS color value usable in inline
+ * styles for swatch backgrounds. Reads `--color-{token}` directly; modern
+ * browsers accept the resulting `oklch(...)` (or fallback `rgb()`) in
+ * `background-color` without normalization.
+ *
+ * SSR-safe: returns `var(--color-{token})` literal when document is absent.
+ */
+const resolveTailwindColor = (token) => {
+    const cssVar = `--color-${token}`;
+    if (typeof window === "undefined")
+        return `var(${cssVar})`;
+    const resolved = getComputedStyle(document.documentElement)
+        .getPropertyValue(cssVar)
+        .trim();
+    return resolved || `var(${cssVar})`;
+};
+/**
+ * The two non-family base colors users always reach for, shown in their own row
+ * above the spectrum.
+ *
+ * `value` is the resolved background color (used to paint the swatch);
+ * `token` is the Tailwind shade fragment used to build the `text-{token}`
+ * class applied to the editor content.
+ */
+const MONO_COLORS = [
+    { name: "white", value: "#ffffff", token: "white" },
+    { name: "black", value: "#000000", token: "black" },
 ];
 /**
  * Rich Text Editor theme - extends common forms base theme for consistency
@@ -25,20 +94,26 @@ const richTextEditorTheme = {
     containerStyle: `${formsBaseTheme.inputGroupBaseStyle} flex-col min-h-[120px] overflow-hidden`,
     // Editor content area - extends common control base style
     editorStyle: `${formsBaseTheme.controlBaseStyle} min-h-[100px] px-3 py-2 resize-none overflow-y-auto [&_p]:my-1 [&_p:first-child]:mt-0 [&_p:last-child]:mb-0 [&_strong]:font-semibold [&_em]:italic [&_u]:underline data-[state=disabled]:cursor-not-allowed empty:before:content-[attr(data-placeholder)] empty:before:text-[var(--color-text-placeholder)] empty:before:pointer-events-none`,
-    // Toolbar styling (RTE-specific)
-    toolbarStyle: "flex items-center gap-1 p-2 border-b border-[var(--color-border)] bg-white dark:bg-[var(--color-background-secondary)]",
-    // Toolbar button styling
-    toolbarButtonStyle: "inline-flex items-center justify-center size-8 rounded-[calc(var(--radius-base)*0.75)] text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-white active:bg-gray-200 transition-colors duration-300 disabled:opacity-50 disabled:cursor-not-allowed data-[state=active]:bg-[var(--color-background-tertiary)] data-[state=active]:text-[var(--color-text-primary)] data-[state=active]:hover:bg-[var(--color-primary-50)] border border-transparent data-[pressed=true]:bg-[var(--color-primary-50)] data-[pressed=true]:text-[var(--color-primary-900)] data-[pressed=true]:shadow-inner data-[pressed=true]:border-[var(--color-primary-200)]",
-    // Dropdown styling (font size, color picker)
-    dropdownStyle: "fixed z-[1000] min-w-[120px] py-1 bg-white/90 backdrop-blur-md rounded-[var(--form-radius)] shadow-xl ring-1 ring-slate-200 focus:outline-none",
-    // Dropdown item styling
-    dropdownItemStyle: "block w-full px-3 py-2 text-left text-sm text-[var(--color-text-primary)] hover:bg-[var(--color-background-tertiary)] transition-colors duration-150 disabled:opacity-50 disabled:cursor-not-allowed",
+    // Toolbar styling (docked variant)
+    // `rounded-t-[var(--form-radius)]` matches the container's radius so the
+    // toolbar's own bg/backdrop-blur respects the top corners — prevents the
+    // 1px bleed past the parent's `overflow-hidden` clip in Safari/Chromium.
+    toolbarStyle: "flex items-center m-0.5 gap-0.5 p-0.5 rounded-[var(--form-radius)] dark:bg-[var(--color-surface)]/0",
+    // Toolbar styling (floating variant — selection-anchored)
+    floatingToolbarStyle: "flex items-center gap-1 p-1 rounded-xl border border-[var(--color-border)] backdrop-blur-md overflow-hidden",
+    // Toolbar button — single source of truth via data-[state=active]
+    // (aria-pressed remains as proper ARIA on toggle buttons, but styling is decoupled)
+    toolbarButtonStyle: "inline-flex items-center justify-center rounded-[calc(var(--radius-base)*0.85)] border border-transparent bg-transparent text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors duration-300 disabled:opacity-50 disabled:cursor-not-allowed data-[state=active]:bg-[var(--color-background-secondary)] data-[state=active]:text-[var(--color-text-primary)] data-[state=active]:border-[var(--color-border)] data-[state=active]:shadow-inner",
+    // Dropdown surface (visual only — positioning handled at use site via portal)
+    dropdownStyle: "min-w-[120px] max-h-[18rem] overflow-y-auto py-1 backdrop-blur-md rounded-[var(--form-radius)] shadow-xl ring-1 ring-[var(--color-border)] focus:outline-none",
+    // Dropdown item — uses data-[active=true] for selected state
+    dropdownItemStyle: "block w-full px-3 py-2 text-left text-sm text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors duration-150 disabled:opacity-50 disabled:cursor-not-allowed data-[active=true]:bg-[var(--color-primary-50)] data-[active=true]:text-[var(--color-primary-900)] data-[active=true]:dark:bg-[var(--color-primary-400)]/10 data-[active=true]:dark:text-[var(--color-primary-400)]",
     // Separator between toolbar sections
     separatorStyle: "w-px h-6 bg-[var(--color-border)] mx-1",
-    // Color picker grid layout
-    colorPickerStyle: "flex flex-wrap gap-1 w-[152px]",
-    // Color swatch button
-    colorSwatchStyle: "size-6 rounded-[calc(var(--radius-base)*0.75)] cursor-pointer hover:scale-105 transition-transform focus:outline-none focus:ring-2 focus:ring-[var(--color-primary)] focus:ring-offset-1",
+    // Color picker layout — column of family rows, plus optional Recent + Mono rows
+    colorPickerStyle: "flex flex-col gap-1 p-2 w-fit",
+    // Color swatch button (original size + rounding)
+    colorSwatchStyle: "size-6 rounded-[calc(var(--radius-base)*0.75)] cursor-pointer hover:scale-105 transition-transform focus:outline-none focus:ring-2 focus:ring-[var(--color-primary)] focus:ring-offset-1 data-[active=true]:ring-2 data-[active=true]:ring-[var(--color-primary)] data-[active=true]:ring-offset-1 border border-[var(--color-border)]",
     // Size variants - use common form sizes for consistency
     sizes: {
         sm: `${formsBaseTheme.sizes.sm.text} min-h-[80px]`,
@@ -51,4 +126,4 @@ const richTextEditorTheme = {
     helperText: formsBaseTheme.helperText,
 };
 
-export { colorOptions, richTextEditorTheme };
+export { MONO_COLORS, TAILWIND_COLOR_FAMILIES, TAILWIND_SHADE_LABELS, getTailwindShadeTokens, resolveTailwindColor, richTextEditorTheme };

package/dist/components/forms/RichTextEditor/RichTextEditor.types.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { SurfaceElevation } from '../../../theme/SurfaceContext';
 /**
  * Rich Text Editor component props
  * @property {RichTextEditorSize} size - The size of the editor
@@ -19,9 +20,15 @@ export interface RichTextEditorProps extends Omit<React.HTMLAttributes<HTMLDivEl
     /** The state of the editor (default, disabled, invalid) */
     state?: RichTextEditorState;
     /** Optional label text for the editor */
-    label?: string;
+    label?: React.ReactNode;
     /** Optional helper text displayed below the editor */
-    helperText?: string;
+    helperText?: React.ReactNode;
+    /**
+     * Error message shown instead of `helperText` when `state="invalid"`.
+     * Takes precedence over `helperText` while invalid; `helperText` is
+     * unaffected/still shown as normal otherwise.
+     */
+    errorMessage?: React.ReactNode;
     /** The HTML content value */
     value?: string;
     /** Callback when content changes */
@@ -48,6 +55,37 @@ export interface RichTextEditorProps extends Omit<React.HTMLAttributes<HTMLDivEl
     toolbar?: ToolbarConfig;
     /** Component-level theme overrides */
     theme?: RichTextEditorThemeOverrides;
+    /**
+     * Custom list of font families shown by the `fontFamily` toolbar tool.
+     * If omitted, ships with a curated default set (system Default + 8 Google Fonts).
+     * Provide your own list when you self-host fonts or want a custom curation.
+     */
+    fontFamilies?: FontFamilyOption[];
+    /**
+     * Whether the editor should lazy-load Google Fonts when picked.
+     * Defaults to `true`. Set to `false` if you load fonts yourself
+     * (e.g. via `next/font` or a `<link>` in your app head) — the picker still
+     * applies the font, but no network request is fired.
+     */
+    loadFontsOnDemand?: boolean;
+    /**
+     * Optional HTML sanitizer function applied before setting innerHTML.
+     * Receives raw HTML string, must return sanitized HTML string.
+     * Recommended: pass DOMPurify.sanitize for robust XSS protection.
+     * If not provided, a basic built-in sanitizer strips script tags and on* event handlers.
+     *
+     * @example
+     * import DOMPurify from 'dompurify';
+     * <RichTextEditor sanitize={DOMPurify.sanitize} />
+     */
+    sanitize?: (html: string) => string;
+    /**
+     * Pin the floating toolbar / dropdown surface elevation rung (overrides the
+     * automatic relative lift) — a rung number (1–8) or a semantic alias.
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the floating surface's base rung. */
+    lift?: boolean;
 }
 export type RichTextEditorSize = 'sm' | 'md' | 'lg';
 export type RichTextEditorState = 'default' | 'disabled' | 'invalid';
@@ -67,8 +105,27 @@ export interface ToolbarConfig {
 /**
  * Available toolbar tools
  */
-export type ToolbarTool = 'bold' | 'italic' | 'underline' | 'fontSize' | 'textColor' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'undo' | 'redo' | 'separator';
-export type RichTextFontSizeKey = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
+export type ToolbarTool = 'bold' | 'italic' | 'underline' | 'fontWeight' | 'fontFamily' | 'fontSize' | 'lineHeight' | 'letterSpacing' | 'textColor' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'undo' | 'redo' | 'separator';
+/**
+ * Font family option used by the RichTextEditor font picker.
+ * - `key` is the stable identifier matched against the current selection.
+ * - `family` is the canonical Google Fonts family name (used to build the load URL).
+ *   Omit for system fonts (e.g. "Default" or "Sans") — they will not be lazy-loaded.
+ * - `stack` is the CSS font-family value applied to the selection. Always include
+ *   safe fallbacks so text remains readable while the font is loading.
+ * - `weights` is the optional list of weights to request (defaults to all 9).
+ */
+export interface FontFamilyOption {
+    key: string;
+    label: string;
+    stack: string;
+    family?: string;
+    weights?: number[];
+}
+export type RichTextFontSizeKey = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | '8xl' | '9xl';
+export type RichTextFontWeightKey = 'thin' | 'extralight' | 'light' | 'normal' | 'medium' | 'semibold' | 'bold' | 'extrabold' | 'black';
+export type RichTextLineHeightKey = 'tight' | 'snug' | 'normal' | 'relaxed' | 'loose';
+export type RichTextLetterSpacingKey = 'tighter' | 'tight' | 'normal' | 'wide' | 'wider' | 'widest';
 /**
  * Text formatting state
  */
@@ -78,6 +135,10 @@ export interface FormattingState {
     underline: boolean;
     textAlign: 'left' | 'center' | 'right' | 'justify';
     fontSize: RichTextFontSizeKey;
+    fontWeight: RichTextFontWeightKey;
+    fontFamily: string;
+    lineHeight: RichTextLineHeightKey;
+    letterSpacing: RichTextLetterSpacingKey;
     textColor: string;
 }
 /**
@@ -98,8 +159,10 @@ export interface RichTextEditorThemeOverrides {
     containerStyle?: string;
     /** ContentEditable element style */
     editorStyle?: string;
-    /** Toolbar container style */
+    /** Toolbar container style (docked variant) */
     toolbarStyle?: string;
+    /** Floating toolbar container style (selection-anchored variant) */
+    floatingToolbarStyle?: string;
     /** Toolbar button style */
     toolbarButtonStyle?: string;
     /** Size variants */
@@ -121,6 +184,7 @@ export interface RichTextEditorTheme {
     containerStyle: string;
     editorStyle: string;
     toolbarStyle: string;
+    floatingToolbarStyle: string;
     toolbarButtonStyle: string;
     dropdownStyle: string;
     dropdownItemStyle: string;

package/dist/components/forms/RichTextEditor/index.d.ts

@@ -1,3 +1,3 @@
-export { RichTextEditor } from './RichTextEditor';
-export type { RichTextEditorProps, RichTextEditorSize, RichTextEditorState, ToolbarConfig, ToolbarTool, FormattingState, ColorOption, RichTextEditorTheme, RichTextEditorThemeOverrides, } from './RichTextEditor.types';
+export { RichTextEditor, DEFAULT_FONT_FAMILY_OPTIONS, loadGoogleFont, } from './RichTextEditor';
+export type { RichTextEditorProps, RichTextEditorSize, RichTextEditorState, ToolbarConfig, ToolbarTool, FormattingState, FontFamilyOption, ColorOption, RichTextEditorTheme, RichTextEditorThemeOverrides, } from './RichTextEditor.types';
 export { richTextEditorTheme, colorOptions } from './RichTextEditor.theme';

package/dist/components/forms/Select/Select.animations.js

@@ -1,32 +1,24 @@
+"use client";
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { getOverlayMenuVariants } from '../../../theme/animations.js';
+
 /**
  * Creates direction-aware dropdown animation variants for the Select component
  * @param isFlipped - Whether the dropdown is positioned above (flipped) or below the trigger
  * @returns Animation variants that match the positioning direction
  */
-const createDropdownAnimations = (isFlipped) => ({
-    initial: {
-        opacity: 0,
-        y: isFlipped ? 10 : -10, // Animate from opposite direction when flipped
-        scale: 0.95,
-    },
-    visible: {
-        opacity: 1,
-        y: 0,
-        scale: 1,
-        transition: {
-            duration: 0.2,
-            ease: 'easeOut'
-        }
-    },
-    exit: {
-        opacity: 0,
-        y: isFlipped ? 10 : -10, // Exit in same direction as entry
-        scale: 0.95,
-        transition: {
-            duration: 0.15,
-            ease: 'easeIn'
-        }
-    }
-});
+const createDropdownAnimations = (isFlipped) => {
+    const side = isFlipped ? 'top' : 'bottom';
+    return getOverlayMenuVariants(side, {
+        scale: 0.97,
+        shift: 6,
+    });
+};
+/**
+ * Default dropdown animation variants for backward compatibility
+ * @deprecated Use createDropdownAnimations() for better UX with direction awareness
+ */
+createDropdownAnimations(false);
 
 export { createDropdownAnimations };

package/dist/components/forms/Select/Select.d.ts

@@ -14,6 +14,8 @@ export interface SelectContextValue<T = any> extends UseSelectStateReturn<T> {
     theme: SelectThemeOverrides;
     /** Whether search is enabled */
     searchable: boolean;
+    /** Placeholder text for the search input */
+    searchPlaceholder: string;
     /** Whether typeahead is enabled */
     enableTypeahead: boolean;
     /** Button ref (alias for triggerRef for backward compatibility) */
@@ -44,6 +46,8 @@ export interface SelectProviderProps<T = any> {
     theme?: SelectThemeOverrides;
     /** Whether search is enabled */
     searchable?: boolean;
+    /** Placeholder text for the search input */
+    searchPlaceholder?: string;
     /** Whether typeahead is enabled */
     enableTypeahead?: boolean;
 }
@@ -68,7 +72,7 @@ export interface SelectProviderProps<T = any> {
  * </SelectProvider>
  * ```
  */
-export declare function SelectProvider<T = any>({ children, selectState, size, componentState, theme: themeOverrides, searchable, enableTypeahead, }: SelectProviderProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function SelectProvider<T = any>({ children, selectState, size, componentState, theme: themeOverrides, searchable, searchPlaceholder, enableTypeahead, }: SelectProviderProps<T>): import("react/jsx-runtime").JSX.Element;
 /**
  * Select Button Component
  */
@@ -79,6 +83,10 @@ export declare const SelectButton: React.FC<SelectButtonProps>;
 export interface SelectOptionsExtendedProps extends SelectOptionsProps {
     /** Custom trigger ref - if provided, uses this instead of buttonRef from context */
     triggerRef?: React.RefObject<HTMLElement>;
+    /** id applied to the listbox element for aria-controls matching */
+    listboxId?: string;
+    /** id of the element that labels the listbox (e.g. the field's FormLabel) */
+    "aria-labelledby"?: string;
 }
 /**
  * Select Options Component
@@ -87,7 +95,7 @@ export declare const SelectOptions: React.FC<SelectOptionsExtendedProps>;
 /**
  * Select Option Component
  */
-export declare const SelectOption: <T extends any>({ value, isSelected, disabled, className, onSelect, children, }: SelectOptionProps<T>) => import("react/jsx-runtime").JSX.Element;
-export declare const Select: <T extends any>(props: SelectProps<T> & React.RefAttributes<HTMLDivElement>) => React.ReactElement | null;
+export declare const SelectOption: <T extends any>({ value, isSelected, disabled, className, onSelect, children, }: SelectOptionProps<T>) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Select: <T = unknown>(props: SelectProps<T> & React.RefAttributes<HTMLDivElement>) => React.ReactElement | null;
 export { useSelectState };
 export type { UseSelectStateProps, UseSelectStateReturn };