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

package/dist/test/render.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+import { RenderOptions } from "@testing-library/react";
+/**
+ * Renders with the provider stack every component in the library expects at
+ * runtime: `ThemeProvider` (component theme overrides context) wrapping
+ * `SurfaceProvider` pinned to the page floor rung (1) — the same substrate a
+ * top-level component sits on in a real app.
+ */
+export declare function renderWithProviders(ui: React.ReactElement, options?: Omit<RenderOptions, "wrapper">): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries"), HTMLElement, HTMLElement>;
+export { screen, within, waitFor, act, fireEvent } from "@testing-library/react";
+export { default as userEvent } from "@testing-library/user-event";

package/dist/test/setup.d.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";

package/dist/theme/SurfaceContext.d.ts

@@ -0,0 +1,98 @@
+import React, { ReactNode } from "react";
+/**
+ * Relative-elevation engine (Fluid Functionalism substrate context).
+ *
+ * Surfaces live on an 8-rung ladder (`--surface-1…8`). Instead of a fixed colour, a
+ * participating surface (Card, Modal, Popover, Dropdown…) reads the rung it is sitting
+ * ON from context and paints **one or more rungs above it** — PURE-RELATIVE — then
+ * provides its own rung to its children so nesting accumulates. The colour therefore
+ * always tracks the background (a menu on the page / in a popover / in a dialog renders
+ * three different shades). In light mode rungs 3–8 are all white, so the lift shows via
+ * the doubling shadow ladder rather than colour (`surfaceClasses` drives both).
+ *
+ * React context flows through portals (it follows the render tree, not the DOM), so a
+ * `<SurfaceProvider>` written as an overlay's JSX ancestor reaches its portaled content
+ * with no special threading.
+ */
+/** An elevation rung. The page/body floor is rung 1. */
+export type SurfaceLevel = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** What callers may pass to an `elevation` prop: a raw rung or a semantic alias. */
+export type SurfaceElevation = SurfaceLevel | "background" | "surface" | "raised" | "overlay";
+/** Resolve a `SurfaceElevation` (semantic name or number) to a concrete rung. */
+export declare const resolveElevation: (elevation: SurfaceElevation) => SurfaceLevel;
+export interface SurfaceClassOptions {
+    /** Paint at 80% opacity (for frosted overlays that also set `backdrop-blur`). */
+    translucent?: boolean;
+    /** Include the per-rung elevation shadow (default `true`). */
+    shadow?: boolean;
+}
+/**
+ * Background + shadow utility classes for a rung. Place FIRST in `cn(...)` so a caller's
+ * `className` (the shadcn override) always wins.
+ *
+ * Returns a plain space-joined literal — the bg and shadow classes never conflict, so there
+ * is nothing for `twMerge` to resolve here. The call site already runs the result through
+ * `cn(...)`; running `twMerge` a second time inside would be pure waste on a hot render path.
+ */
+export declare const surfaceClasses: (level: SurfaceLevel, options?: SurfaceClassOptions) => string;
+/** The rung the current subtree is sitting ON (the substrate). Page floor = 1. */
+export declare const useSurfaceLevel: () => SurfaceLevel;
+/** Pure-relative lift: a child sitting on `substrate` paints `substrate + offset`. */
+export declare const liftLevel: (substrate: SurfaceLevel, offset?: number) => SurfaceLevel;
+export interface SurfaceProviderProps {
+    /** The rung this surface paints at — becomes the substrate for descendants. */
+    level: SurfaceLevel;
+    children: ReactNode;
+}
+/** Tell descendants which rung they are sitting on. */
+export declare const SurfaceProvider: ({ level, children }: SurfaceProviderProps) => React.ReactElement;
+/** Public override props every participating surface component accepts. */
+export interface SurfaceElevationProps {
+    /**
+     * Pin the surface elevation rung (overrides the automatic relative lift) — a rung
+     * number (1–8) or a semantic alias (`"surface"`/`"raised"`/`"overlay"`…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the component's base rung. */
+    lift?: boolean;
+}
+export interface UseSurfaceElevationArgs extends SurfaceElevationProps {
+    /**
+     * The component's semantic identity rung — the rung it paints when grounded or when
+     * lifting is opted out (`lift={false}`). Card = 3, Modal/Drawer = 4, overlays = 5.
+     */
+    baseRung: SurfaceLevel;
+    /** Pure-relative lift above the substrate (default 1). Tune per component visually. */
+    offset?: number;
+    /**
+     * Backdrop overlay — render at a FIXED rung (`baseRung`) ignoring the inherited
+     * substrate. A Modal/Drawer/CommandPalette/Toast covers the viewport (or portals to a
+     * page-level toaster), so it is conceptually grounded on the floor no matter where its
+     * JSX lives; without this it would inherit the rung of whatever container its `<Modal>`
+     * tag happens to sit inside and render too bright. Anchored overlays (Dropdown/Popover/
+     * Tooltip/…) leave this `false` so they lift relative to their host.
+     */
+    ground?: boolean;
+}
+/**
+ * Resolve the rung a participating component should paint at. Override precedence:
+ * `elevation` (pin) › `ground`/`lift={false}` (pin to baseRung) › pure-relative `substrate + offset`.
+ *
+ * NOTE: the relative default deliberately does NOT floor at `baseRung` (`max(base, …)`) — that
+ * would pin a standalone overlay to a fixed rung and reproduce the "menu is the same colour as a
+ * low host" bug. The lift is purely relative; `baseRung` is the grounded / opt-out target.
+ */
+export declare function useSurfaceElevation({ baseRung, offset, elevation, lift, ground, }: UseSurfaceElevationArgs): SurfaceLevel;
+export interface SurfaceProps extends React.HTMLAttributes<HTMLDivElement>, SurfaceClassOptions {
+    /** Explicit rung/semantic to pin; omit to lift one rung above the substrate. */
+    elevation?: SurfaceElevation;
+    /** Relative lift above substrate when `elevation` is omitted (default 1). */
+    offset?: number;
+    children?: ReactNode;
+}
+/**
+ * Generic surface primitive / region escape hatch: paints itself at a rung and provides
+ * that rung to its children. Use to manually control elevation for a subtree
+ * (`<Surface elevation="surface">…</Surface>`).
+ */
+export declare const Surface: ({ elevation, offset, translucent, shadow, className, children, ...rest }: SurfaceProps) => React.ReactElement;

package/dist/theme/SurfaceContext.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useContext } from 'react';
+import { cn } from '../utils/cn.js';
+
+const SEMANTIC_RUNG = {
+    background: 1,
+    surface: 3,
+    raised: 4,
+    overlay: 5,
+};
+const MIN_LEVEL = 1;
+const MAX_LEVEL = 8;
+const clampLevel = (n) => Math.max(MIN_LEVEL, Math.min(MAX_LEVEL, Math.round(n)));
+/** Resolve a `SurfaceElevation` (semantic name or number) to a concrete rung. */
+const resolveElevation = (elevation) => typeof elevation === "number" ? clampLevel(elevation) : SEMANTIC_RUNG[elevation];
+// ── purge-safe literal maps ───────────────────────────────────────────────────────
+// ⚠️ Every class MUST stay a verbatim literal (mirror Grid.theme.ts). Tailwind v4 scans
+// this source text to decide which utilities to emit — NEVER build `surface-${n}` at
+// runtime or the classes drop from the scan and break in production CSS.
+const SURFACE_BG = {
+    1: "bg-[var(--surface-1)]",
+    2: "bg-[var(--surface-2)]",
+    3: "bg-[var(--surface-3)]",
+    4: "bg-[var(--surface-4)]",
+    5: "bg-[var(--surface-5)]",
+    6: "bg-[var(--surface-6)]",
+    7: "bg-[var(--surface-7)]",
+    8: "bg-[var(--surface-8)]",
+};
+const SURFACE_BG_TRANSLUCENT = {
+    1: "bg-[var(--surface-1)]/80",
+    2: "bg-[var(--surface-2)]/80",
+    3: "bg-[var(--surface-3)]/80",
+    4: "bg-[var(--surface-4)]/80",
+    5: "bg-[var(--surface-5)]/80",
+    6: "bg-[var(--surface-6)]/80",
+    7: "bg-[var(--surface-7)]/80",
+    8: "bg-[var(--surface-8)]/80",
+};
+const SURFACE_SHADOW = {
+    1: "shadow-surface-1",
+    2: "shadow-surface-2",
+    3: "shadow-surface-3",
+    4: "shadow-surface-4",
+    5: "shadow-surface-5",
+    6: "shadow-surface-6",
+    7: "shadow-surface-7",
+    8: "shadow-surface-8",
+};
+// Each surface publishes `--field-fill` = the rung ONE ABOVE itself, so a text field placed inside
+// it lifts a step out of the surface (lighter in dark; still white in light, where rungs 3–8 are all
+// white). Inputs read `bg-[var(--field-fill)]` and inherit this via the CSS cascade — no per-input
+// wiring. Clamped at 8. Arbitrary-property utilities are purge-safe literals (like the maps above).
+const SURFACE_FIELD_FILL = {
+    1: "[--field-fill:var(--surface-2)]",
+    2: "[--field-fill:var(--surface-3)]",
+    3: "[--field-fill:var(--surface-4)]",
+    4: "[--field-fill:var(--surface-5)]",
+    5: "[--field-fill:var(--surface-6)]",
+    6: "[--field-fill:var(--surface-7)]",
+    7: "[--field-fill:var(--surface-8)]",
+    8: "[--field-fill:var(--surface-8)]",
+};
+/**
+ * Background + shadow utility classes for a rung. Place FIRST in `cn(...)` so a caller's
+ * `className` (the shadcn override) always wins.
+ *
+ * Returns a plain space-joined literal — the bg and shadow classes never conflict, so there
+ * is nothing for `twMerge` to resolve here. The call site already runs the result through
+ * `cn(...)`; running `twMerge` a second time inside would be pure waste on a hot render path.
+ */
+const surfaceClasses = (level, options = {}) => {
+    const { translucent = false, shadow = true } = options;
+    const bg = (translucent ? SURFACE_BG_TRANSLUCENT : SURFACE_BG)[level];
+    const field = SURFACE_FIELD_FILL[level];
+    return shadow ? `${bg} ${SURFACE_SHADOW[level]} ${field}` : `${bg} ${field}`;
+};
+// ── context ───────────────────────────────────────────────────────────────────────
+const SurfaceLevelContext = createContext(1);
+/** The rung the current subtree is sitting ON (the substrate). Page floor = 1. */
+const useSurfaceLevel = () => useContext(SurfaceLevelContext);
+/** Pure-relative lift: a child sitting on `substrate` paints `substrate + offset`. */
+const liftLevel = (substrate, offset = 1) => clampLevel(substrate + offset);
+/** Tell descendants which rung they are sitting on. */
+const SurfaceProvider = ({ level, children }) => (jsx(SurfaceLevelContext.Provider, { value: level, children: children }));
+/**
+ * Resolve the rung a participating component should paint at. Override precedence:
+ * `elevation` (pin) › `ground`/`lift={false}` (pin to baseRung) › pure-relative `substrate + offset`.
+ *
+ * NOTE: the relative default deliberately does NOT floor at `baseRung` (`max(base, …)`) — that
+ * would pin a standalone overlay to a fixed rung and reproduce the "menu is the same colour as a
+ * low host" bug. The lift is purely relative; `baseRung` is the grounded / opt-out target.
+ */
+function useSurfaceElevation({ baseRung, offset = 1, elevation, lift = true, ground = false, }) {
+    const substrate = useSurfaceLevel();
+    if (elevation != null)
+        return resolveElevation(elevation);
+    if (ground || !lift)
+        return baseRung;
+    return liftLevel(substrate, offset);
+}
+/**
+ * Generic surface primitive / region escape hatch: paints itself at a rung and provides
+ * that rung to its children. Use to manually control elevation for a subtree
+ * (`<Surface elevation="surface">…</Surface>`).
+ */
+const Surface = ({ elevation, offset = 1, translucent, shadow, className, children, ...rest }) => {
+    const substrate = useSurfaceLevel();
+    const level = elevation != null ? resolveElevation(elevation) : liftLevel(substrate, offset);
+    return (jsx(SurfaceProvider, { level: level, children: jsx("div", { className: cn(surfaceClasses(level, { translucent, shadow }), className), ...rest, children: children }) }));
+};
+
+export { Surface, SurfaceProvider, liftLevel, resolveElevation, surfaceClasses, useSurfaceElevation, useSurfaceLevel };

package/dist/theme/ThemeContext.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useMemo, useContext } from 'react';
+
+// Create context with default theme
+const ThemeContext = createContext({
+    theme: {
+        components: {
+        // Default component themes
+        }
+    }
+});
+const ThemeProvider = ({ theme = {}, children }) => {
+    const value = useMemo(() => ({ theme }), [theme]);
+    return (jsx(ThemeContext.Provider, { value: value, children: children }));
+};
+const useTheme = () => useContext(ThemeContext);
+
+export { ThemeProvider, useTheme };

package/dist/theme/animations.d.ts

@@ -0,0 +1,75 @@
+import { Variants } from "motion/react";
+export type AnimationSide = "top" | "bottom" | "left" | "right";
+/**
+ * Centered spring presets for unified motion across the library.
+ * Designed to feel natural, responsive, and premium.
+ */
+export declare const springs: {
+    /** High-end tuning for small overlays (dropdowns, popovers, select menus, tooltips). Damping ratio ≈ 0.9. */
+    premium: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+    };
+    /** Soft, elegant tuning for larger panels (drawers, dialogs, slide-overs). Damping ratio ≈ 0.93. */
+    smooth: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+        mass: number;
+    };
+    /** Quick, responsive tuning for minor state transitions (switches, toggles, badge bounces). */
+    snappy: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+    };
+    /** Organic, relaxed tuning for decorative or slow-moving elements. */
+    gentle: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+    };
+};
+/**
+ * Standard cubic-bezier easing presets for CSS/framer-motion tween animations.
+ */
+export declare const easings: {
+    easeOut: [number, number, number, number];
+    easeIn: [number, number, number, number];
+    easeInOut: [number, number, number, number];
+};
+interface OverlayVariantsOptions {
+    /** The starting scale factor of the menu. Defaults to 0.97. */
+    scale?: number;
+    /** The shift distance in pixels from the target side. Defaults to 6. */
+    shift?: number;
+    /** The transition configuration for the enter state. Defaults to springs.premium. */
+    enterTransition?: any;
+    /** The transition configuration for the exit state. Defaults to 0.12s easeIn. */
+    exitTransition?: any;
+}
+/**
+ * Generates context-aware animation variants for popups, dropdowns, and selects.
+ * Automatically handles slide direction and opacity based on which side the overlay opens from.
+ *
+ * @param side The viewport side where the menu opened relative to the trigger.
+ * @param options Styling and transition customisations.
+ */
+export declare const getOverlayMenuVariants: (side: AnimationSide, options?: OverlayVariantsOptions) => Variants;
+/**
+ * Unified backdrop animations (fade-in / fade-out) for drawers, modals, and popovers.
+ */
+export declare const overlayBackdropAnimations: Variants;
+interface ExpandCollapseVariantsOptions {
+    /** The stagger duration between child node animations. Defaults to 0.03. */
+    staggerChildren?: number;
+    /** The delay before starting child node animations. Defaults to 0.03. */
+    delayChildren?: number;
+}
+/**
+ * Generates smooth vertical expand/collapse animation variants for collapsible panels
+ * (like Accordions, Tree nodes, and Collapsible menus).
+ */
+export declare const getExpandCollapseVariants: (options?: ExpandCollapseVariantsOptions) => Variants;
+export {};

package/dist/theme/animations.js

@@ -0,0 +1,132 @@
+"use client";
+/**
+ * Centered spring presets for unified motion across the library.
+ * Designed to feel natural, responsive, and premium.
+ */
+const springs = {
+    /** High-end tuning for small overlays (dropdowns, popovers, select menus, tooltips). Damping ratio ≈ 0.9. */
+    premium: {
+        type: "spring",
+        stiffness: 380,
+        damping: 35,
+    },
+    /** Soft, elegant tuning for larger panels (drawers, dialogs, slide-overs). Damping ratio ≈ 0.93. */
+    smooth: {
+        type: "spring",
+        stiffness: 280,
+        damping: 28,
+        mass: 0.8,
+    },
+    /** Quick, responsive tuning for minor state transitions (switches, toggles, badge bounces). */
+    snappy: {
+        type: "spring",
+        stiffness: 500,
+        damping: 30,
+    },
+    /** Organic, relaxed tuning for decorative or slow-moving elements. */
+    gentle: {
+        type: "spring",
+        stiffness: 200,
+        damping: 25,
+    },
+};
+/**
+ * Standard cubic-bezier easing presets for CSS/framer-motion tween animations.
+ */
+const easings = {
+    easeOut: [0, 0, 0.2, 1],
+    easeIn: [0.4, 0, 1, 1],
+    easeInOut: [0.4, 0, 0.2, 1],
+};
+/**
+ * Generates context-aware animation variants for popups, dropdowns, and selects.
+ * Automatically handles slide direction and opacity based on which side the overlay opens from.
+ *
+ * @param side The viewport side where the menu opened relative to the trigger.
+ * @param options Styling and transition customisations.
+ */
+const getOverlayMenuVariants = (side, options = {}) => {
+    const { scale = 0.97, shift = 6, enterTransition = springs.premium, exitTransition = { duration: 0.12, ease: "easeIn" }, } = options;
+    const closedShift = side === "top"
+        ? { y: shift }
+        : side === "left"
+            ? { x: shift }
+            : side === "right"
+                ? { x: -shift }
+                : { y: -shift };
+    return {
+        initial: { opacity: 0, scale, x: 0, y: 0, ...closedShift },
+        hidden: { opacity: 0, scale, x: 0, y: 0, ...closedShift },
+        visible: {
+            opacity: 1,
+            scale: 1,
+            x: 0,
+            y: 0,
+            transition: enterTransition,
+        },
+        animate: {
+            opacity: 1,
+            scale: 1,
+            x: 0,
+            y: 0,
+            transition: enterTransition,
+        },
+        exit: {
+            opacity: 0,
+            scale,
+            x: 0,
+            y: 0,
+            ...closedShift,
+            transition: exitTransition,
+        },
+    };
+};
+/**
+ * Unified backdrop animations (fade-in / fade-out) for drawers, modals, and popovers.
+ */
+const overlayBackdropAnimations = {
+    initial: { opacity: 0 },
+    animate: { opacity: 1, transition: { duration: 0.15 } },
+    exit: { opacity: 0, transition: { duration: 0.1 } },
+};
+/**
+ * Generates smooth vertical expand/collapse animation variants for collapsible panels
+ * (like Accordions, Tree nodes, and Collapsible menus).
+ */
+const getExpandCollapseVariants = (options = {}) => {
+    const { staggerChildren = 0.03, delayChildren = 0.03 } = options;
+    return {
+        expanded: {
+            height: "auto",
+            opacity: 1,
+            transition: {
+                height: {
+                    type: "spring",
+                    stiffness: 280,
+                    damping: 28,
+                    mass: 0.8,
+                },
+                opacity: { duration: 0.2 },
+                staggerChildren,
+                delayChildren,
+            },
+        },
+        collapsed: {
+            height: 0,
+            opacity: 0,
+            transition: {
+                height: {
+                    type: "spring",
+                    stiffness: 280,
+                    damping: 28,
+                    mass: 0.8,
+                },
+                opacity: { duration: 0.15 },
+                staggerChildren: staggerChildren * 0.5,
+                staggerDirection: -1,
+            },
+        },
+    };
+};
+
+export { easings, getExpandCollapseVariants, getOverlayMenuVariants, overlayBackdropAnimations, springs };

package/dist/theme/index.d.ts

@@ -0,0 +1,5 @@
+export { ThemeProvider, useTheme } from "./ThemeContext";
+export type { ThemeConfig, ThemeProviderProps } from "./ThemeContext";
+export { Surface, SurfaceProvider, surfaceClasses, useSurfaceLevel, useSurfaceElevation, liftLevel, resolveElevation, } from "./SurfaceContext";
+export type { SurfaceLevel, SurfaceElevation, SurfaceElevationProps, SurfaceClassOptions, SurfaceProviderProps, SurfaceProps, UseSurfaceElevationArgs, } from "./SurfaceContext";
+export * from "./animations";