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

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

@@ -1,15 +1,31 @@
 import { ReactNode } from "react";
-export interface NavItemProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface NavItemSubmenuItem {
+    /** Label text */
+    children: ReactNode;
+    /** Link href */
+    href?: string;
+    /** Click handler */
+    onClick?: () => void;
+    /** Whether this sub-item is active */
+    active?: boolean;
+    /** Whether this sub-item is disabled */
+    isDisabled?: boolean;
+    /** Notification count/dot on the sub-item */
+    notification?: number | boolean;
+    /** Start content (icon) for the sub-item */
+    startContent?: ReactNode;
+}
+export interface NavItemProps extends React.HTMLAttributes<HTMLElement> {
     /**
      * Content of the navigation item
      */
     children: ReactNode;
     /**
-     * Start content (icon), replaces `icon`
+     * Start content (icon)
      */
     startContent?: ReactNode;
     /**
-     * End content (badge/arrow), replaces `badge`
+     * End content (badge/arrow)
      */
     endContent?: ReactNode;
     /**
@@ -21,15 +37,9 @@ export interface NavItemProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     shortcut?: string;
     /**
-     * Legacy icon prop (mapped to startContent)
-     * @deprecated Use startContent instead
-     */
-    icon?: ReactNode;
-    /**
-     * Legacy badge prop (mapped to endContent)
-     * @deprecated Use endContent instead
+     * Notification indicator. Pass a number for a count badge, or true for a dot.
      */
-    badge?: string | number;
+    notification?: number | boolean;
     /**
      * Link href (for navigation)
      */
@@ -49,28 +59,31 @@ export interface NavItemProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     isDisabled?: boolean;
     /**
-     * Alias for isDisabled
-     * @deprecated Use isDisabled
-     */
-    disabled?: boolean;
-    /**
-     * Whether the item represents a danger action
-     */
-    isDanger?: boolean;
-    /**
-     * Whether the item has a submenu
+     * Whether the item has a submenu (manual mode).
+     * If `items` is provided, this is set automatically.
      * @default false
      */
     hasSubmenu?: boolean;
     /**
-     * Whether the submenu is expanded (for multi-level navigation)
+     * Whether the submenu is expanded (controlled mode for manual submenus).
      * @default false
      */
     expanded?: boolean;
     /**
-     * Callback when submenu is toggled
+     * Callback when submenu is toggled (manual mode)
      */
     onToggleExpanded?: () => void;
+    /**
+     * Self-contained submenu items. When provided, NavItem manages its own
+     * expand/collapse state internally. Children items automatically get
+     * level={parentLevel + 1}.
+     */
+    items?: NavItemSubmenuItem[];
+    /**
+     * Whether the self-contained submenu is expanded by default
+     * @default false
+     */
+    defaultExpanded?: boolean;
     /**
      * Nesting level for indentation (0, 1, 2)
      * @default 0
@@ -94,14 +107,14 @@ export interface NavItemTheme {
         default: string;
         active: string;
         disabled: string;
-        hover: string;
     };
-    iconStates?: {
-        default?: string;
-        active?: string;
-        disabled?: string;
-        hover?: string;
+    iconStates: {
+        default: string;
+        active: string;
+        disabled: string;
     };
+    /** Keyboard focus-visible ring */
+    focusStyle: string;
     levels: {
         0: string;
         1: string;
@@ -111,6 +124,10 @@ export interface NavItemTheme {
         container: string;
         icon: string;
     };
+    density: {
+        compact: string;
+    };
+    notificationDot: string;
 }
 export interface NavItemThemeOverrides {
     baseStyle?: string;
@@ -120,14 +137,13 @@ export interface NavItemThemeOverrides {
         default: string;
         active: string;
         disabled: string;
-        hover: string;
     }>;
     iconStates?: Partial<{
         default: string;
         active: string;
         disabled: string;
-        hover: string;
     }>;
+    focusStyle?: string;
     levels?: Partial<{
         0: string;
         1: string;
@@ -137,32 +153,8 @@ export interface NavItemThemeOverrides {
         container: string;
         icon: string;
     }>;
-    danger?: string;
-}
-export interface NavItemTheme {
-    baseStyle: string;
-    icon: string;
-    text: string;
-    states: {
-        default: string;
-        active: string;
-        disabled: string;
-        hover: string;
-    };
-    iconStates?: {
-        default?: string;
-        active?: string;
-        disabled?: string;
-        hover?: string;
-    };
-    levels: {
-        0: string;
-        1: string;
-        2: string;
-    };
-    collapsed: {
-        container: string;
-        icon: string;
-    };
-    danger?: string;
+    density?: Partial<{
+        compact: string;
+    }>;
+    notificationDot?: string;
 }

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

@@ -1,2 +1,2 @@
 export { NavItem } from './NavItem';
-export type { NavItemProps, NavItemTheme, NavItemThemeOverrides } from './NavItem.types';
+export type { NavItemProps, NavItemSubmenuItem, NavItemTheme, NavItemThemeOverrides } from './NavItem.types';

package/dist/components/core/OfflineIndicator/OfflineIndicator.animations.d.ts

@@ -0,0 +1,22 @@
+import type { Variants } from "motion/react";
+import type { OfflineIndicatorPosition, OfflineIndicatorVariant } from "./OfflineIndicator.types";
+/**
+ * Custom spring preset for offline indicator to give it a satisfying, subtle bounce.
+ */
+export declare const indicatorSpring: {
+    type: "spring";
+    stiffness: number;
+    damping: number;
+    mass: number;
+};
+/**
+ * Generates context-aware animation variants for OfflineIndicator.
+ * Dynamically adjusts translation side/axis based on screen placement.
+ */
+/**
+ * Fade-only variants for prefers-reduced-motion users — the status pill
+ * still appears/disappears (it's a role="status" signal), just without
+ * translation, scale, or bounce.
+ */
+export declare const reducedMotionIndicatorVariants: Variants;
+export declare const getOfflineIndicatorVariants: (position: OfflineIndicatorPosition, variant: OfflineIndicatorVariant) => Variants;

package/dist/components/core/OfflineIndicator/OfflineIndicator.animations.js

@@ -0,0 +1,54 @@
+"use client";
+/**
+ * Custom spring preset for offline indicator to give it a satisfying, subtle bounce.
+ */
+const indicatorSpring = {
+    type: "spring",
+    stiffness: 260,
+    damping: 26,
+    mass: 1,
+};
+/**
+ * Generates context-aware animation variants for OfflineIndicator.
+ * Dynamically adjusts translation side/axis based on screen placement.
+ */
+/**
+ * Fade-only variants for prefers-reduced-motion users — the status pill
+ * still appears/disappears (it's a role="status" signal), just without
+ * translation, scale, or bounce.
+ */
+const reducedMotionIndicatorVariants = {
+    initial: { opacity: 0 },
+    animate: { opacity: 1, transition: { duration: 0.15 } },
+    exit: { opacity: 0, transition: { duration: 0.15 } },
+};
+const getOfflineIndicatorVariants = (position, variant) => {
+    const isTop = position.startsWith("top");
+    // Toast variants slide and scale, Banner variants just slide to maintain bleed styling
+    const yOffset = isTop ? -24 : 24;
+    const initialScale = variant === "banner" ? 1 : 0.92;
+    return {
+        initial: {
+            opacity: 0,
+            y: yOffset,
+            scale: initialScale,
+        },
+        animate: {
+            opacity: 1,
+            y: 0,
+            scale: 1,
+            transition: indicatorSpring,
+        },
+        exit: {
+            opacity: 0,
+            y: yOffset,
+            scale: initialScale,
+            transition: {
+                duration: 0.18,
+                ease: "easeIn",
+            },
+        },
+    };
+};
+
+export { getOfflineIndicatorVariants, indicatorSpring, reducedMotionIndicatorVariants };

package/dist/components/core/OfflineIndicator/OfflineIndicator.js

@@ -1,12 +1,19 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useEffect, useMemo } from 'react';
-import { SignalSlashIcon, CheckCircleIcon } from '@heroicons/react/24/solid';
-import { AnimatePresence, motion } from 'motion/react';
+import { WifiSlash, CheckCircle } from '@phosphor-icons/react';
+import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { useNetworkStatus } from '../../../hooks/useNetworkStatus.js';
 import { getDefaultQueue } from '../../../utils/actionQueue.js';
+import { Link } from '../Link/Link.js';
+import { reducedMotionIndicatorVariants, getOfflineIndicatorVariants } from './OfflineIndicator.animations.js';
 import { offlineIndicatorTheme } from './OfflineIndicator.theme.js';
 
+const isOfflineIndicatorAction = (action) => typeof action === "object" &&
+    action !== null &&
+    "label" in action &&
+    "onClick" in action;
 /**
  * OfflineIndicator - Visual indicator for offline status
  *
@@ -20,9 +27,10 @@ import { offlineIndicatorTheme } from './OfflineIndicator.theme.js';
  * // Custom position and variant
  * <OfflineIndicator position="bottom-right" variant="badge" />
  */
-const OfflineIndicator = React__default.forwardRef(({ position = "top", showQueueCount = false, queue, variant = "toast", autoHideOnline = true, autoHideDelay = 5000, offlineMessage = "You're offline", onlineMessage = "Back online", className, }, ref) => {
-    var _a, _b;
+const OfflineIndicator = React__default.forwardRef(({ position = "top", showQueueCount = false, queue, variant = "toast", autoHideOnline = true, autoHideDelay = 5000, offlineMessage = "You're offline", onlineMessage = "Back online", action, className, }, ref) => {
+    var _a, _b, _c;
     const theme = offlineIndicatorTheme;
+    const shouldReduceMotion = useReducedMotion();
     const { isOnline, wasOffline } = useNetworkStatus();
     const [isVisible, setIsVisible] = useState(false);
     const [queueSize, setQueueSize] = useState(0);
@@ -72,29 +80,21 @@ const OfflineIndicator = React__default.forwardRef(({ position = "top", showQueu
         autoHideOnline,
         autoHideDelay,
     ]);
-    // Animation variants
-    const animationVariants = useMemo(() => ({
-        initial: {
-            opacity: 0,
-            y: position.startsWith("top") ? -20 : 20,
-            scale: 0.95,
-        },
-        animate: {
-            opacity: 1,
-            y: 0,
-            scale: 1,
-        },
-        exit: {
-            opacity: 0,
-            y: position.startsWith("top") ? -20 : 20,
-            scale: 0.95,
-        },
-    }), [position]);
+    // Animation variants — fade-only under prefers-reduced-motion (§12)
+    const animationVariants = useMemo(() => shouldReduceMotion
+        ? reducedMotionIndicatorVariants
+        : getOfflineIndicatorVariants(position, variant), [shouldReduceMotion, position, variant]);
     const isOffline = !isOnline;
-    const Icon = isOffline ? SignalSlashIcon : CheckCircleIcon;
+    const Icon = isOffline ? WifiSlash : CheckCircle;
     const message = isOffline ? offlineMessage : onlineMessage;
     const stateStyle = isOffline ? theme.offline : theme.online;
-    return (jsx(AnimatePresence, { children: isVisible && (jsxs(motion.div, { ref: ref, initial: "initial", animate: "animate", exit: "exit", variants: animationVariants, transition: { duration: 0.2, ease: "easeOut" }, className: cn(theme.base, (_a = theme.positions) === null || _a === void 0 ? void 0 : _a[position], (_b = theme.variants) === null || _b === void 0 ? void 0 : _b[variant], stateStyle, className), role: "status", "aria-live": "polite", children: [jsx(Icon, { className: theme.icon, "aria-hidden": "true" }), jsxs("span", { className: theme.message, children: [message, showQueueCount && queueSize > 0 && isOffline && (jsxs("span", { className: theme.queueCount, children: ["(", queueSize, " action", queueSize !== 1 ? "s" : "", " queued)"] }))] })] })) }));
+    // No `layout` on the root motion.div: its FLIP transform would fight the
+    // y/scale enter/exit variants on the same element (the documented
+    // concurrent layout+transform trap). Content-size changes animate via the
+    // children's layout="position" instead.
+    return (jsx(AnimatePresence, { children: isVisible && (jsxs(motion.div, { ref: ref, initial: "initial", animate: "animate", exit: "exit", variants: animationVariants, className: cn(theme.base, variant === "banner"
+                ? (_a = theme.bannerPositions) === null || _a === void 0 ? void 0 : _a[position]
+                : (_b = theme.positions) === null || _b === void 0 ? void 0 : _b[position], (_c = theme.variants) === null || _c === void 0 ? void 0 : _c[variant], stateStyle, className), role: "status", "aria-live": "polite", children: [jsx("div", { className: "relative size-3.5 flex-shrink-0", children: jsx(AnimatePresence, { mode: "popLayout", children: jsx(motion.div, { initial: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, scale: 0.5, rotate: -45 }, animate: shouldReduceMotion ? { opacity: 1 } : { opacity: 1, scale: 1, rotate: 0 }, exit: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, scale: 0.5, rotate: 45 }, transition: { duration: 0.25 }, className: "absolute inset-0 flex items-center justify-center", children: jsx(Icon, { className: "size-full", "aria-hidden": "true" }) }, isOffline ? "offline" : "online") }) }), jsxs(motion.span, { layout: shouldReduceMotion ? false : "position", className: theme.message, children: [message, jsx(AnimatePresence, { mode: "popLayout", children: showQueueCount && queueSize > 0 && isOffline && (jsxs(motion.span, { initial: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, scale: 0.8 }, animate: shouldReduceMotion ? { opacity: 1 } : { opacity: 1, scale: 1 }, exit: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, scale: 0.8 }, transition: { duration: 0.18 }, className: theme.queueCount, children: ["(", queueSize, " action", queueSize !== 1 ? "s" : "", " queued)"] })) })] }), jsx(AnimatePresence, { children: action != null && isOffline && (jsx(motion.div, { layout: shouldReduceMotion ? false : "position", initial: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, scale: 0.9 }, animate: shouldReduceMotion ? { opacity: 1 } : { opacity: 1, scale: 1 }, exit: shouldReduceMotion ? { opacity: 0 } : { opacity: 0, scale: 0.9 }, transition: { duration: 0.2 }, className: "inline-flex items-center flex-shrink-0", children: isOfflineIndicatorAction(action) ? (jsx(Link, { size: "sm", onClick: action.onClick, className: theme.action, children: action.label })) : (action) })) })] })) }));
 });
 OfflineIndicator.displayName = "OfflineIndicator";
 

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

@@ -1,5 +1,5 @@
 const offlineIndicatorTheme = {
-    base: "fixed z-50 flex items-center gap-2 transition-all duration-300 select-none ",
+    base: "fixed z-50 flex items-center gap-1.5 transition-colors duration-300 select-none",
     positions: {
         top: "top-4 left-1/2 -translate-x-1/2",
         bottom: "bottom-4 left-1/2 -translate-x-1/2",
@@ -8,14 +8,33 @@ const offlineIndicatorTheme = {
         "bottom-left": "bottom-4 left-4",
         "bottom-right": "bottom-4 right-4",
     },
+    // Banner is an edge-to-edge bar, so it collapses every position to the
+    // flush viewport edge — only the top/bottom half of `position` matters.
+    bannerPositions: {
+        top: "top-0",
+        bottom: "bottom-0",
+        "top-left": "top-0",
+        "top-right": "top-0",
+        "bottom-left": "bottom-0",
+        "bottom-right": "bottom-0",
+    },
     variants: {
-        banner: "w-full left-0 right-0 px-4 py-1 justify-center rounded-none shadow-real-lg",
-        toast: "px-3 py-2 rounded-[var(--radius-base)] shadow-real-lg",
+        // translate-x-0 cancels the centered positions' -translate-x-1/2 (cn's
+        // tailwind-merge lets the variant win) — without it the full-width bar
+        // is dragged left by half its own width and clips off-screen.
+        banner: "w-full left-0 right-0 translate-x-0 px-4 py-1 justify-center rounded-none shadow-real-lg",
+        toast: "px-3 py-2 rounded-[var(--toast-radius)] shadow-real-xl",
     },
-    offline: "bg-[var(--color-neutral-900)]/90 backdrop-blur-sm text-white",
-    online: "bg-[var(--color-success)]/90 backdrop-blur-sm text-white",
-    icon: "size-4 flex-shrink-0",
-    message: "text-xs font-medium",
+    // Filled-neutral pill: the bare neutral token flips light/dark on its own
+    // (dark near-black pill in light mode, light pill in dark mode) and
+    // -contrast auto-derives — no hand-picked rungs or dark: inversions (§3).
+    offline: "bg-[var(--color-mono)]/90 backdrop-blur-sm text-[var(--color-mono-contrast)]",
+    online: "bg-[var(--color-success)]/90 backdrop-blur-sm text-[var(--color-success-contrast)]",
+    // text-inherit keeps the link legible on the inverse pill in BOTH modes
+    // (near-black in light, near-white in dark) — a fixed Link color can't.
+    action: "text-xs font-semibold text-inherit",
+    icon: "size-3.5 flex-shrink-0",
+    message: "text-xs font-medium -tracking-[0.025em]",
     queueCount: "text-xs opacity-80 ml-1",
 };
 

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

@@ -1,4 +1,12 @@
+import type { ReactNode } from "react";
 import type { ActionQueue } from "../../../utils/actionQueue";
+/**
+ * Declarative action rendered after the offline message (e.g. a retry link)
+ */
+export interface OfflineIndicatorAction {
+    label: string;
+    onClick: () => void;
+}
 /**
  * Position options for OfflineIndicator
  */
@@ -27,6 +35,11 @@ export interface OfflineIndicatorProps {
     offlineMessage?: string;
     /** Custom online message (shown briefly when reconnecting) */
     onlineMessage?: string;
+    /**
+     * Action shown next to the message while offline — pass `{ label, onClick }`
+     * for a link-styled button (mirrors Toast's `action`), or any ReactNode.
+     */
+    action?: OfflineIndicatorAction | ReactNode;
     /** Additional class names */
     className?: string;
 }
@@ -38,6 +51,8 @@ export interface OfflineIndicatorTheme {
     base?: string;
     /** Position-specific styles */
     positions?: Record<OfflineIndicatorPosition, string>;
+    /** Position overrides for the full-bleed banner variant (flush to the viewport edge, no inset) */
+    bannerPositions?: Record<OfflineIndicatorPosition, string>;
     /** Variant-specific styles */
     variants?: {
         banner?: string;
@@ -48,6 +63,8 @@ export interface OfflineIndicatorTheme {
     offline?: string;
     /** Online (reconnected) state styles */
     online?: string;
+    /** Action link styles */
+    action?: string;
     /** Icon styles */
     icon?: string;
     /** Message text styles */

package/dist/components/core/PageHeading/PageHeading.js

@@ -1,4 +1,5 @@
-import { jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { pageHeadingTheme } from './PageHeading.theme.js';
@@ -8,12 +9,16 @@ import { PageHeadingTitle } from './PageHeadingTitle.js';
 import { PageHeadingSubtitle } from './PageHeadingSubtitle.js';
 import { PageHeadingActions } from './PageHeadingActions.js';
 
-const PageHeadingRoot = React__default.forwardRef(({ children, className, separator = true, theme: customTheme = {}, ...props }, ref) => {
+const PageHeadingRoot = React__default.forwardRef(({ children, className, separator = true, title, subtitle, actions, theme: customTheme = {}, ...props }, ref) => {
     const theme = useMemo(() => ({
         ...pageHeadingTheme,
         ...customTheme,
     }), [customTheme]);
-    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, separator && theme.separatorStyle, className), ...props, children: children }));
+    // Slot-prop mode: any header slot (title/subtitle/actions) composes the
+    // compound parts for us — one render path (reuses the real sub-components).
+    // Otherwise children render raw — the compound API path, unchanged.
+    const hasHeader = Boolean(title || subtitle || actions);
+    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, separator && theme.separatorStyle, className), ...props, children: hasHeader ? (jsxs("div", { className: theme.headerStyle, children: [(title || subtitle) && (jsxs("div", { className: "min-w-0 flex-1", children: [title && jsx(PageHeadingTitle, { children: title }), subtitle && jsx(PageHeadingSubtitle, { children: subtitle })] })), actions && jsx(PageHeadingActions, { children: actions })] })) : (children) }));
 });
 PageHeadingRoot.displayName = "PageHeading";
 // Create compound component with proper typing

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

@@ -1,8 +1,8 @@
 const pageHeadingTheme = {
     baseStyle: "flex flex-col pb-6 mb-6",
-    headerStyle: "flex items-center gap-4",
-    titleStyle: "text-2xl font-semibold tracking-tight text-[var(--color-text-primary)]",
-    subtitleStyle: "text-sm text-[var(--color-text-muted)] mt-1",
+    headerStyle: "flex flex-col items-start sm:flex-row sm:items-center gap-4",
+    titleStyle: "text-[length:var(--page-heading-title-size)] leading-[1.4] font-bold text-[var(--color-text-primary)]",
+    subtitleStyle: "text-sm text-[var(--color-text-secondary)] mt-1",
     actionsStyle: "sm:ml-auto flex items-center gap-2 shrink-0",
     iconStyle: "flex items-center justify-center shrink-0 text-[var(--color-text-muted)]",
     separatorStyle: "border-b border-[var(--color-border)] mt-4",

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

@@ -17,9 +17,20 @@ export interface PageHeadingThemeOverrides {
     iconStyle?: string;
     separatorStyle?: string;
 }
-export interface PageHeadingProps extends HTMLAttributes<HTMLDivElement> {
+export interface PageHeadingProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     children?: ReactNode;
     className?: string;
+    /**
+     * Heading title (serializable slot). Setting any slot-prop
+     * (`title`/`subtitle`/`actions`) switches PageHeading into managed mode —
+     * it composes the compound parts internally. Setting none renders
+     * `children` raw (pure compound mode).
+     */
+    title?: ReactNode;
+    /** Secondary line under the title (serializable slot). */
+    subtitle?: ReactNode;
+    /** Right-aligned actions next to the title. */
+    actions?: ReactNode;
     /** Show bottom separator. @default true */
     separator?: boolean;
     theme?: PageHeadingThemeOverrides;
@@ -42,7 +53,7 @@ export interface PageHeadingIconProps extends HTMLAttributes<HTMLDivElement> {
 }
 export interface PageHeadingBackButtonProps {
     /** Text label next to the back arrow. @default "Back" */
-    label?: string;
+    label?: ReactNode;
     onClick?: () => void;
     className?: string;
 }

package/dist/components/core/PageHeading/PageHeadingBackButton.js

@@ -1,11 +1,14 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
-import { ArrowLeftIcon } from '@heroicons/react/20/solid';
-import { Button } from '../Button/Button.js';
+import { ArrowLeft } from '@phosphor-icons/react';
+import { Link } from '../Link/Link.js';
 
 const PageHeadingBackButton = React__default.forwardRef(({ label = "Back", onClick, className, ...props }, ref) => {
-    return (jsxs(Button, { ref: ref, variant: "link", color: "neutral", size: "sm", onClick: onClick, className: cn("mb-2 w-fit", className), ...props, children: [jsx(ArrowLeftIcon, { className: "size-4" }), label] }));
+    return (jsxs(Link, { ref: ref, color: "mono", size: "sm", onClick: onClick, className: cn("mb-2 w-fit", className), ...props, children: [jsx(ArrowLeft, { className: "size-4" }), typeof label === 'string'
+                ? jsx("span", { children: label })
+                : label] }));
 });
 PageHeadingBackButton.displayName = "PageHeadingBackButton";
 

package/dist/components/core/Pagination/Pagination.js

@@ -1,8 +1,9 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useMemo, useCallback } from 'react';
 import { paginationTheme } from './Pagination.theme.js';
 import { cn } from '../../../utils/cn.js';
-import { ChevronDoubleLeftIcon, ChevronLeftIcon, ChevronRightIcon, ChevronDoubleRightIcon } from '@heroicons/react/24/outline';
+import { CaretDoubleLeft, CaretLeft, CaretRight, CaretDoubleRight } from '@phosphor-icons/react';
 
 /**
  * Internal PaginationItem component for page numbers and ellipsis
@@ -77,14 +78,19 @@ const Pagination = React__default.forwardRef(({ currentPage, totalPages, onPageC
     }
     const isFirstPage = currentPage === 1;
     const isLastPage = currentPage === totalPages;
-    return (jsxs("nav", { ref: ref, role: "navigation", "aria-label": "Pagination Navigation", className: cn(theme.baseStyle, className), ...props, children: [showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(1), "aria-label": "Go to first page", children: [jsx(ChevronDoubleLeftIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "First" })] })), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(currentPage - 1), "aria-label": `Go to previous page (${currentPage - 1})`, children: [jsx(ChevronLeftIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Previous" })] })), paginationRange.map((pageNumber, index) => {
+    // Clamp the page numbers used in Previous/Next aria-labels so a disabled
+    // button at a boundary never announces an out-of-range page (e.g. "(0)"
+    // on page 1, or "(totalPages + 1)" on the last page).
+    const previousPageLabelNumber = Math.max(currentPage - 1, 1);
+    const nextPageLabelNumber = Math.min(currentPage + 1, totalPages);
+    return (jsxs("nav", { ref: ref, role: "navigation", "aria-label": "Pagination Navigation", className: cn(theme.baseStyle, className), ...props, children: [showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(1), "aria-label": "Go to first page", children: [jsx(CaretDoubleLeft, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "First" })] })), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isFirstPage, onClick: () => handlePageChange(currentPage - 1), "aria-label": `Go to previous page (${previousPageLabelNumber})`, children: [jsx(CaretLeft, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Previous" })] })), paginationRange.map((pageNumber, index) => {
                 if (pageNumber === "...") {
-                    return (jsxs(PaginationItem, { size: size, variant: "ellipsis", isDisabled: true, "aria-label": "More pages", role: "separator", children: [jsx("span", { "aria-hidden": "true", children: "\u2026" }), jsx("span", { className: "sr-only", children: "More pages" })] }, `ellipsis-${index}`));
+                    return (jsx("span", { role: "separator", "aria-hidden": "true", children: "\u2026" }, `ellipsis-${index}`));
                 }
                 const page = pageNumber;
                 const isActive = page === currentPage;
                 return (jsxs(PaginationItem, { size: size, variant: "page", isActive: isActive, onClick: () => handlePageChange(page), "aria-label": isActive ? `Page ${page}, current page` : `Go to page ${page}`, children: [page, isActive && jsx("span", { className: "sr-only", children: "(current)" })] }, page));
-            }), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(currentPage + 1), "aria-label": `Go to next page (${currentPage + 1})`, children: [jsx(ChevronRightIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Next" })] })), showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(totalPages), "aria-label": "Go to last page", children: [jsx(ChevronDoubleRightIcon, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Last" })] }))] }));
+            }), showPrevNext && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(currentPage + 1), "aria-label": `Go to next page (${nextPageLabelNumber})`, children: [jsx(CaretRight, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Next" })] })), showFirstLast && (jsxs(PaginationItem, { size: size, isDisabled: isLastPage, onClick: () => handlePageChange(totalPages), "aria-label": "Go to last page", children: [jsx(CaretDoubleRight, { className: "w-4 h-4" }), jsx("span", { className: "sr-only", children: "Last" })] }))] }));
 });
 Pagination.displayName = "Pagination";
 

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

@@ -1,13 +1,5 @@
-import { PaginationSize } from "./Pagination.types";
-/**
- * Simplified theme structure for the Pagination component with unified item styling
- */
-export interface PaginationTheme {
-    baseStyle: string;
-    itemStyle: string;
-    itemSizes: Record<PaginationSize, string>;
-    ellipsisStyle: string;
-}
+import { PaginationTheme } from "./Pagination.types";
+export type { PaginationTheme } from "./Pagination.types";
 /**
  * Default theme for the Pagination component using modern neutral colors
  */

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

@@ -9,19 +9,19 @@ const paginationTheme = {
     // Dark mode: neutral-800 background, lighter text, neutral-600 borders
     itemStyle: "inline-flex items-center justify-center font-medium rounded-[var(--form-radius)] transition-all duration-200 ease-in-out " +
         // Focus styles
-        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 dark:focus-visible:ring-offset-[var(--color-neutral-900)] " +
+        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 dark:focus-visible:ring-offset-[var(--color-mono-900)] " +
         // Base state - light
         "cursor-pointer bg-white border border-transparent text-[var(--color-text-muted)] " +
         // Base state - dark
-        "dark:bg-[var(--color-neutral-800)] dark:text-[var(--color-neutral-400)] dark:border-transparent " +
+        "dark:bg-transparent dark:text-[var(--color-text-secondary)] dark:border-transparent " +
         // Hover state - light
-        "hover:text-[var(--color-text-primary)] hover:bg-neutral-50 hover:border-[var(--color-border)] " +
+        "hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] hover:border-[var(--color-border)] " +
         // Hover state - dark
-        "dark:hover:bg-[var(--color-neutral-700)] dark:hover:text-[var(--color-neutral-200)] dark:hover:border-[var(--color-neutral-600)] " +
+        "dark:hover:bg-[var(--color-surface-hover)] dark:hover:text-[var(--color-text-primary)] dark:hover:border-[var(--color-border)]/0 " +
         // Active state - light
         "data-[active=true]:bg-white data-[active=true]:border-[var(--color-border)] data-[active=true]:text-[var(--color-text-primary)] " +
         // Active state - dark (uses primary color accent)
-        "dark:data-[active=true]:bg-[var(--color-primary-900)] dark:data-[active=true]:border-[var(--color-primary-700)] dark:data-[active=true]:text-[var(--color-primary-300)] " +
+        "dark:data-[active=true]:bg-[var(--color-mono-800)] dark:data-[active=true]:border-none dark:data-[active=true]:text-[var(--color-text-primary)] " +
         // Disabled state
         "data-[disabled=true]:opacity-50 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:pointer-events-none",
     // Unified item sizes
@@ -30,7 +30,7 @@ const paginationTheme = {
         md: "size-10 min-w-[2.5rem] text-sm",
     },
     // Ellipsis styles
-    ellipsisStyle: "inline-flex items-center justify-center font-medium text-[var(--color-text-muted)] dark:text-[var(--color-neutral-500)] cursor-default pointer-events-none",
+    ellipsisStyle: "inline-flex items-center justify-center font-medium text-[var(--color-text-muted)] cursor-default pointer-events-none",
 };
 
 export { paginationTheme };

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

@@ -1,5 +1,4 @@
 import React from "react";
-import { PaginationTheme } from "./Pagination.theme";
 /**
  * Pagination component props
  * @property {number} currentPage - The current active page number (1-based)
@@ -31,6 +30,17 @@ export interface PaginationProps extends React.HTMLAttributes<HTMLDivElement> {
     theme?: Partial<PaginationTheme>;
 }
 export type PaginationSize = "sm" | "md";
+/**
+ * Simplified theme structure for the Pagination component with unified item styling
+ * (declared here, not in Pagination.theme.ts, so types→theme imports never
+ * happen — keeps the theme/types import graph one-directional)
+ */
+export interface PaginationTheme {
+    baseStyle: string;
+    itemStyle: string;
+    itemSizes: Record<PaginationSize, string>;
+    ellipsisStyle: string;
+}
 /**
  * Internal pagination item props
  */