@particle-academy/react-fancy 4.17.1 → 4.18.0

package/dist/index.d.cts

@@ -1,8 +1,46 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ElementType, AnchorHTMLAttributes, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, FormHTMLAttributes, TdHTMLAttributes, HTMLAttributes, ComponentType, CSSProperties, ReactElement, RefObject } from 'react';
+import { ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, FormHTMLAttributes, TdHTMLAttributes, HTMLAttributes, ComponentType, CSSProperties, ReactElement, RefObject } from 'react';
 import { ClassValue } from 'clsx';
 
 type Size = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * What a navigation primitive owes a router.
+ *
+ * Every nav surface here — `Navbar.Item`, `Sidebar.Item`, `Menu.Item`,
+ * `MobileMenu.Item`, `Breadcrumbs.Item` — used to hardcode a plain `<a href>`.
+ * That is a FULL PAGE LOAD in every client-routed app, and the only way around
+ * it was to nest a router `<Link>` inside the item: an anchor inside an anchor,
+ * which is invalid HTML and the same nested-anchor shape that already cost this
+ * suite an SSR hydration bug.
+ *
+ * `as` is the seam {@link ButtonProps.as} already had. It is router-agnostic on
+ * purpose — one prop serves Inertia, TanStack Router, React Router and Next
+ * rather than a package per router:
+ *
+ * ```tsx
+ * // href-based routers (Inertia, Next)
+ * <Navbar.Item as={Link} href="/dashboard">Dashboard</Navbar.Item>
+ *
+ * // to-based routers (TanStack Router, React Router) — `to` reaches the Link
+ * // through the forwarded rest props
+ * <Navbar.Item as={Link} to="/dashboard">Dashboard</Navbar.Item>
+ * ```
+ *
+ * Link mode engages on `href` OR `as`, because a `to`-based router never passes
+ * an `href` and would otherwise silently render the non-interactive fallback.
+ */
+interface NavigableProps {
+    /** Target URL. Renders link mode with a plain `<a>` unless `as` is given. */
+    href?: string;
+    /**
+     * Link-mode element override — the component to render INSTEAD of the plain
+     * `<a>`, e.g. a router's `<Link>` so navigation happens client-side. Receives
+     * `className`, the item's `data-*` handles, and every unrecognized prop, so
+     * router-specific props (`to`, `params`, `preload`, `search`) pass straight
+     * through. Ignored in button mode.
+     */
+    as?: ElementType;
+}
 /**
  * The full Tailwind v4 named color palette — every default hue, including all
  * five gray families. Components that accept a `color` should type it as this
@@ -1827,9 +1865,8 @@ interface BreadcrumbsProps {
     shrink?: boolean;
     className?: string;
 }
-interface BreadcrumbsItemProps {
+interface BreadcrumbsItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     active?: boolean;
     /**
      * Navigate by callback instead of by URL, for a crumb with no href.
@@ -1843,7 +1880,7 @@ interface BreadcrumbsItemProps {
     className?: string;
 }
 
-declare function BreadcrumbsItem({ children, href, active, onClick, className, }: BreadcrumbsItemProps): react.JSX.Element;
+declare function BreadcrumbsItem({ children, href, as: As, active, onClick, className, ...rest }: BreadcrumbsItemProps): react.JSX.Element;
 declare namespace BreadcrumbsItem {
     var displayName: string;
 }
@@ -1869,9 +1906,8 @@ interface NavbarItemsProps {
     children: ReactNode;
     className?: string;
 }
-interface NavbarItemProps {
+interface NavbarItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     active?: boolean;
     className?: string;
 }
@@ -1889,7 +1925,7 @@ declare namespace NavbarItems {
     var displayName: string;
 }
 
-declare function NavbarItem({ children, href, active, className, }: NavbarItemProps): react.JSX.Element;
+declare function NavbarItem({ children, href, as: As, active, className, ...rest }: NavbarItemProps): react.JSX.Element;
 declare namespace NavbarItem {
     var displayName: string;
 }
@@ -2434,9 +2470,8 @@ interface MenuProps {
     orientation?: MenuOrientation;
     className?: string;
 }
-interface MenuItemProps {
+interface MenuItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
@@ -2460,7 +2495,7 @@ interface MenuContextValue {
     orientation: MenuOrientation;
 }
 
-declare function MenuItem({ children, href, icon, active, disabled, badge, onClick, className, }: MenuItemProps): react.JSX.Element;
+declare function MenuItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: MenuItemProps): react.JSX.Element;
 declare namespace MenuItem {
     var displayName: string;
 }
@@ -2499,9 +2534,8 @@ interface SidebarProps {
     collapseMode?: SidebarCollapseMode;
     className?: string;
 }
-interface SidebarItemProps {
+interface SidebarItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
@@ -2530,7 +2564,7 @@ interface SidebarContextValue {
     setCollapsed: (collapsed: boolean) => void;
 }
 
-declare function SidebarItem({ children, href, icon, active, disabled, badge, onClick, className, }: SidebarItemProps): react.JSX.Element;
+declare function SidebarItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: SidebarItemProps): react.JSX.Element;
 declare namespace SidebarItem {
     var displayName: string;
 }
@@ -2574,9 +2608,8 @@ interface MobileMenuBottomBarProps {
     children: ReactNode;
     className?: string;
 }
-interface MobileMenuItemProps {
+interface MobileMenuItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
@@ -2598,7 +2631,7 @@ declare namespace MobileMenuBottomBar {
     var displayName: string;
 }
 
-declare function MobileMenuItem({ children, href, icon, active, disabled, badge, onClick, className, }: MobileMenuItemProps): react.JSX.Element;
+declare function MobileMenuItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: MobileMenuItemProps): react.JSX.Element;
 declare namespace MobileMenuItem {
     var displayName: string;
 }

package/dist/index.d.ts

@@ -1,8 +1,46 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ElementType, AnchorHTMLAttributes, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, FormHTMLAttributes, TdHTMLAttributes, HTMLAttributes, ComponentType, CSSProperties, ReactElement, RefObject } from 'react';
+import { ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, FormHTMLAttributes, TdHTMLAttributes, HTMLAttributes, ComponentType, CSSProperties, ReactElement, RefObject } from 'react';
 import { ClassValue } from 'clsx';
 
 type Size = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * What a navigation primitive owes a router.
+ *
+ * Every nav surface here — `Navbar.Item`, `Sidebar.Item`, `Menu.Item`,
+ * `MobileMenu.Item`, `Breadcrumbs.Item` — used to hardcode a plain `<a href>`.
+ * That is a FULL PAGE LOAD in every client-routed app, and the only way around
+ * it was to nest a router `<Link>` inside the item: an anchor inside an anchor,
+ * which is invalid HTML and the same nested-anchor shape that already cost this
+ * suite an SSR hydration bug.
+ *
+ * `as` is the seam {@link ButtonProps.as} already had. It is router-agnostic on
+ * purpose — one prop serves Inertia, TanStack Router, React Router and Next
+ * rather than a package per router:
+ *
+ * ```tsx
+ * // href-based routers (Inertia, Next)
+ * <Navbar.Item as={Link} href="/dashboard">Dashboard</Navbar.Item>
+ *
+ * // to-based routers (TanStack Router, React Router) — `to` reaches the Link
+ * // through the forwarded rest props
+ * <Navbar.Item as={Link} to="/dashboard">Dashboard</Navbar.Item>
+ * ```
+ *
+ * Link mode engages on `href` OR `as`, because a `to`-based router never passes
+ * an `href` and would otherwise silently render the non-interactive fallback.
+ */
+interface NavigableProps {
+    /** Target URL. Renders link mode with a plain `<a>` unless `as` is given. */
+    href?: string;
+    /**
+     * Link-mode element override — the component to render INSTEAD of the plain
+     * `<a>`, e.g. a router's `<Link>` so navigation happens client-side. Receives
+     * `className`, the item's `data-*` handles, and every unrecognized prop, so
+     * router-specific props (`to`, `params`, `preload`, `search`) pass straight
+     * through. Ignored in button mode.
+     */
+    as?: ElementType;
+}
 /**
  * The full Tailwind v4 named color palette — every default hue, including all
  * five gray families. Components that accept a `color` should type it as this
@@ -1827,9 +1865,8 @@ interface BreadcrumbsProps {
     shrink?: boolean;
     className?: string;
 }
-interface BreadcrumbsItemProps {
+interface BreadcrumbsItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     active?: boolean;
     /**
      * Navigate by callback instead of by URL, for a crumb with no href.
@@ -1843,7 +1880,7 @@ interface BreadcrumbsItemProps {
     className?: string;
 }
 
-declare function BreadcrumbsItem({ children, href, active, onClick, className, }: BreadcrumbsItemProps): react.JSX.Element;
+declare function BreadcrumbsItem({ children, href, as: As, active, onClick, className, ...rest }: BreadcrumbsItemProps): react.JSX.Element;
 declare namespace BreadcrumbsItem {
     var displayName: string;
 }
@@ -1869,9 +1906,8 @@ interface NavbarItemsProps {
     children: ReactNode;
     className?: string;
 }
-interface NavbarItemProps {
+interface NavbarItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     active?: boolean;
     className?: string;
 }
@@ -1889,7 +1925,7 @@ declare namespace NavbarItems {
     var displayName: string;
 }
 
-declare function NavbarItem({ children, href, active, className, }: NavbarItemProps): react.JSX.Element;
+declare function NavbarItem({ children, href, as: As, active, className, ...rest }: NavbarItemProps): react.JSX.Element;
 declare namespace NavbarItem {
     var displayName: string;
 }
@@ -2434,9 +2470,8 @@ interface MenuProps {
     orientation?: MenuOrientation;
     className?: string;
 }
-interface MenuItemProps {
+interface MenuItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
@@ -2460,7 +2495,7 @@ interface MenuContextValue {
     orientation: MenuOrientation;
 }
 
-declare function MenuItem({ children, href, icon, active, disabled, badge, onClick, className, }: MenuItemProps): react.JSX.Element;
+declare function MenuItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: MenuItemProps): react.JSX.Element;
 declare namespace MenuItem {
     var displayName: string;
 }
@@ -2499,9 +2534,8 @@ interface SidebarProps {
     collapseMode?: SidebarCollapseMode;
     className?: string;
 }
-interface SidebarItemProps {
+interface SidebarItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
@@ -2530,7 +2564,7 @@ interface SidebarContextValue {
     setCollapsed: (collapsed: boolean) => void;
 }
 
-declare function SidebarItem({ children, href, icon, active, disabled, badge, onClick, className, }: SidebarItemProps): react.JSX.Element;
+declare function SidebarItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: SidebarItemProps): react.JSX.Element;
 declare namespace SidebarItem {
     var displayName: string;
 }
@@ -2574,9 +2608,8 @@ interface MobileMenuBottomBarProps {
     children: ReactNode;
     className?: string;
 }
-interface MobileMenuItemProps {
+interface MobileMenuItemProps extends NavigableProps {
     children: ReactNode;
-    href?: string;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
@@ -2598,7 +2631,7 @@ declare namespace MobileMenuBottomBar {
     var displayName: string;
 }
 
-declare function MobileMenuItem({ children, href, icon, active, disabled, badge, onClick, className, }: MobileMenuItemProps): react.JSX.Element;
+declare function MobileMenuItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: MobileMenuItemProps): react.JSX.Element;
 declare namespace MobileMenuItem {
     var displayName: string;
 }

package/dist/index.js

@@ -9348,17 +9348,30 @@ var Accordion = Object.assign(AccordionRoot, {
 function BreadcrumbsItem({
   children,
   href,
+  as: As,
   active = false,
   onClick,
-  className
+  className,
+  ...rest
 }) {
   const baseClass = cn(
     "text-sm",
     active ? "font-medium text-zinc-900 dark:text-white" : "text-zinc-500 hover:text-zinc-700 dark:text-zinc-400 dark:hover:text-zinc-300",
     className
   );
-  if (href && !active) {
-    return /* @__PURE__ */ jsx("a", { "data-react-fancy-breadcrumbs-item": "", href, className: baseClass, children });
+  if ((href || As) && !active) {
+    const Link = As ?? "a";
+    return /* @__PURE__ */ jsx(
+      Link,
+      {
+        "data-react-fancy-breadcrumbs-item": "",
+        ...href ? { href } : {},
+        onClick,
+        className: baseClass,
+        ...rest,
+        children
+      }
+    );
   }
   if (onClick && !active) {
     return /* @__PURE__ */ jsx(
@@ -9368,11 +9381,12 @@ function BreadcrumbsItem({
         "data-react-fancy-breadcrumbs-item": "",
         onClick,
         className: cn(baseClass, "cursor-pointer border-0 bg-transparent p-0"),
+        ...rest,
         children
       }
     );
   }
-  return /* @__PURE__ */ jsx("span", { "data-react-fancy-breadcrumbs-item": "", className: baseClass, "aria-current": active ? "page" : void 0, children });
+  return /* @__PURE__ */ jsx("span", { "data-react-fancy-breadcrumbs-item": "", className: baseClass, "aria-current": active ? "page" : void 0, ...rest, children });
 }
 BreadcrumbsItem.displayName = "BreadcrumbsItem";
 function BreadcrumbsDropdown({ items, activeLabel }) {
@@ -9490,18 +9504,30 @@ NavbarItems.displayName = "NavbarItems";
 function NavbarItem({
   children,
   href,
+  as: As,
   active = false,
-  className
+  className,
+  ...rest
 }) {
   const baseClass = cn(
     "rounded-lg px-3 py-2 text-sm font-medium transition-colors",
     active ? "bg-zinc-100 text-zinc-900 dark:bg-zinc-800 dark:text-white" : "text-zinc-600 hover:bg-zinc-50 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-white",
     className
   );
-  if (href) {
-    return /* @__PURE__ */ jsx("a", { "data-react-fancy-navbar-item": "", href, className: baseClass, children });
+  if (href || As) {
+    const Link = As ?? "a";
+    return /* @__PURE__ */ jsx(
+      Link,
+      {
+        "data-react-fancy-navbar-item": "",
+        ...href ? { href } : {},
+        className: baseClass,
+        ...rest,
+        children
+      }
+    );
   }
-  return /* @__PURE__ */ jsx("div", { "data-react-fancy-navbar-item": "", className: baseClass, children });
+  return /* @__PURE__ */ jsx("div", { "data-react-fancy-navbar-item": "", className: baseClass, ...rest, children });
 }
 NavbarItem.displayName = "NavbarItem";
 function NavbarToggle({ className }) {
@@ -12318,21 +12344,25 @@ function useMenu() {
 function MenuItem({
   children,
   href,
+  as: As,
   icon,
   active = false,
   disabled = false,
   badge,
   onClick,
-  className
+  className,
+  ...rest
 }) {
   const { orientation } = useMenu();
   const isVertical = orientation === "vertical";
-  const Tag = href ? "a" : "button";
-  const tagProps = href ? { href } : { type: "button", onClick };
+  const isLink = Boolean(href || As);
+  const Tag = isLink ? As ?? "a" : "button";
+  const tagProps = isLink ? { ...href ? { href } : {}, onClick } : { type: "button", onClick };
   return /* @__PURE__ */ jsxs(
     Tag,
     {
       ...tagProps,
+      ...rest,
       "data-react-fancy-menu-item": "",
       "data-active": active || void 0,
       "aria-current": active ? "page" : void 0,
@@ -12483,16 +12513,19 @@ function getLetters(children) {
 function SidebarItem({
   children,
   href,
+  as: As,
   icon,
   active = false,
   disabled = false,
   badge,
   onClick,
-  className
+  className,
+  ...rest
 }) {
   const { collapsed, collapseMode } = useSidebar();
-  const Tag = href ? "a" : "button";
-  const tagProps = href ? { href } : { type: "button", onClick };
+  const isLink = Boolean(href || As);
+  const Tag = isLink ? As ?? "a" : "button";
+  const tagProps = isLink ? { ...href ? { href } : {}, onClick } : { type: "button", onClick };
   const showIconOnly = collapsed && collapseMode === "icons" && icon;
   const showLetters = collapsed && (collapseMode === "letters" || collapseMode === "icons" && !icon);
   const title = typeof children === "string" ? children : void 0;
@@ -12500,6 +12533,7 @@ function SidebarItem({
     Tag,
     {
       ...tagProps,
+      ...rest,
       "data-react-fancy-sidebar-item": "",
       "data-active": active || void 0,
       "aria-current": active ? "page" : void 0,
@@ -12752,22 +12786,26 @@ MobileMenuBottomBar.displayName = "MobileMenuBottomBar";
 function MobileMenuItem({
   children,
   href,
+  as: As,
   icon,
   active = false,
   disabled = false,
   badge,
   onClick,
-  className
+  className,
+  ...rest
 }) {
   const { variant } = useMobileMenu();
   const isBottomBar = variant === "bottom-bar";
-  const Tag = href ? "a" : "button";
-  const tagProps = href ? { href } : { type: "button", onClick };
+  const isLink = Boolean(href || As);
+  const Tag = isLink ? As ?? "a" : "button";
+  const tagProps = isLink ? { ...href ? { href } : {}, onClick } : { type: "button", onClick };
   if (isBottomBar) {
     return /* @__PURE__ */ jsxs(
       Tag,
       {
         ...tagProps,
+        ...rest,
         "data-react-fancy-mobile-menu-item": "",
         "data-active": active || void 0,
         "aria-current": active ? "page" : void 0,
@@ -12791,6 +12829,7 @@ function MobileMenuItem({
     Tag,
     {
       ...tagProps,
+      ...rest,
       "data-react-fancy-mobile-menu-item": "",
       "data-active": active || void 0,
       "aria-current": active ? "page" : void 0,