@ponti-studios/ui 0.8.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponti-studios/ui",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "private": false,
   "description": "Shared UI component library for Ponti Studios",
   "license": "MIT",

package/src/components/navigation/app-navigation.stories.tsx

@@ -1,11 +1,12 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import * as React from "react";
 
-import { AppNavigation } from "./app-navigation";
+import { Button } from "../primitives/button";
+import { Navigation } from "./app-navigation";
 
-const meta: Meta<typeof AppNavigation> = {
+const meta: Meta<typeof Navigation> = {
   title: "Navigation/AppNavigation",
-  component: AppNavigation,
+  component: Navigation,
   tags: ["autodocs"],
   parameters: {
     layout: "fullscreen",
@@ -18,7 +19,7 @@ type Story = StoryObj<typeof meta>;
 // Shared helpers
 // ---------------------------------------------------------------------------
 
-const defaultLinks: Array<{ href: string; label: string }> = [
+const defaultLinks = [
   { href: "/features", label: "Features" },
   { href: "/pricing", label: "Pricing" },
   { href: "/blog", label: "Blog" },
@@ -45,12 +46,25 @@ function PageContent({
 export const Default: Story = {
   render: () => (
     <>
-      <AppNavigation
-        brand="Acme"
-        brandHref="/"
-        links={defaultLinks}
-        cta={{ href: "/get-started", label: "Get started", variant: "default" }}
-      />
+      <Navigation>
+        <Navigation.Brand>
+          <a href="/">Acme</a>
+        </Navigation.Brand>
+
+        <Navigation.List>
+          {defaultLinks.map((link) => (
+            <Navigation.Item key={link.href} href={link.href}>
+              {link.label}
+            </Navigation.Item>
+          ))}
+        </Navigation.List>
+
+        <Navigation.Action>
+          <Button size="md" asChild>
+            <a href="/get-started">Get started</a>
+          </Button>
+        </Navigation.Action>
+      </Navigation>
       <PageContent />
     </>
   ),
@@ -59,22 +73,99 @@ export const Default: Story = {
 export const NoCta: Story = {
   render: () => (
     <>
-      <AppNavigation brand="Acme" brandHref="/" links={defaultLinks} />
-      <PageContent message="Same nav, no CTA button." />
+      <Navigation>
+        <Navigation.Brand>
+          <a href="/">Acme</a>
+        </Navigation.Brand>
+        <Navigation.List>
+          {defaultLinks.map((link) => (
+            <Navigation.Item key={link.href} href={link.href}>
+              {link.label}
+            </Navigation.Item>
+          ))}
+        </Navigation.List>
+      </Navigation>
+      <PageContent message="Same nav, no Action content." />
     </>
   ),
 };
 
-export const OutlineCta: Story = {
+/**
+ * `Navigation.Item` (and any of the other pieces) support the same
+ * `asChild` composition as `Button`: pass your router's `Link` (or
+ * anything else) as the single child. This story stands in for a router
+ * `Link` with a plain anchor that no-ops on click, since Storybook has no
+ * router.
+ */
+export const WithCustomRouterLink: Story = {
+  render: () => {
+    const activeHref = "/pricing";
+    return (
+      <>
+        <Navigation>
+          <Navigation.Brand>
+            <a href="/" data-router-link="stand-in" onClick={(e) => e.preventDefault()}>
+              Acme
+            </a>
+          </Navigation.Brand>
+
+          <Navigation.List>
+            {defaultLinks.map((link) => (
+              <Navigation.Item key={link.href} asChild active={link.href === activeHref}>
+                <a href={link.href} data-router-link="stand-in" onClick={(e) => e.preventDefault()}>
+                  {link.label}
+                </a>
+              </Navigation.Item>
+            ))}
+          </Navigation.List>
+
+          <Navigation.Action>
+            <Button size="md" asChild>
+              <a href="/get-started" data-router-link="stand-in" onClick={(e) => e.preventDefault()}>
+                Get started
+              </a>
+            </Button>
+          </Navigation.Action>
+        </Navigation>
+        <PageContent message="Every link here is a custom element composed via asChild - open the elements panel to see data-router-link on each one, and the /pricing item's data-active/aria-current." />
+      </>
+    );
+  },
+};
+
+/**
+ * Composition means arbitrary content can sit alongside the link list and
+ * action area without any prop-shape changes to `Navigation` itself.
+ */
+export const WithExtraContent: Story = {
   render: () => (
     <>
-      <AppNavigation
-        brand="Acme"
-        brandHref="/"
-        links={defaultLinks}
-        cta={{ href: "/get-started", label: "Get started", variant: "outline" }}
-      />
-      <PageContent message="The outline CTA keeps the same navigation geometry with a quieter emphasis." />
+      <Navigation>
+        <Navigation.Brand>
+          <a href="/">Acme</a>
+        </Navigation.Brand>
+
+        <Navigation.List>
+          {defaultLinks.slice(0, 2).map((link) => (
+            <Navigation.Item key={link.href} href={link.href}>
+              {link.label}
+            </Navigation.Item>
+          ))}
+        </Navigation.List>
+
+        <input
+          type="search"
+          placeholder="Search..."
+          className="h-9 w-40 rounded-md border bg-background px-3 text-sm"
+        />
+
+        <Navigation.Action>
+          <Button size="md" variant="outline" asChild>
+            <a href="/get-started">Get started</a>
+          </Button>
+        </Navigation.Action>
+      </Navigation>
+      <PageContent message="A search input sits directly between the link list and the action area — no endContent prop needed." />
     </>
   ),
 };

package/src/components/navigation/app-navigation.tsx

@@ -1,160 +1,182 @@
 import { Menu } from "lucide-react";
-import type { ComponentPropsWithoutRef } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import * as React from "react";
 
 import { cn } from "../../lib/utils";
+import { Slot } from "../../lib/slot";
 import { Sheet, SheetClose, SheetContent, SheetTitle, SheetTrigger } from "../overlays/sheet";
 import { Button } from "../primitives/button";
 
-export interface AppNavigationLink {
-  href: string;
-  label: string;
+/** True while rendering inside the mobile Sheet copy of the nav content. */
+const MobileMenuContext = React.createContext(false);
+
+export interface NavigationRootProps {
+  children: ReactNode;
+  ariaLabel?: string;
+  className?: string;
 }
 
-export interface AppNavigationCta {
-  href: string;
-  label: string;
-  variant?: "default" | "outline";
+/**
+ * Sticky nav shell. Compose it with `Navigation.Brand`, `Navigation.List`
+ * (containing `Navigation.Item`s), and any other content — a CTA `Button`,
+ * a search input, a notification bell — as plain children. `Navigation`
+ * only owns the responsive chrome: `Navigation.Brand` stays visible at
+ * every width, everything else collapses into a Sheet-based mobile menu
+ * below `sm`, reusing the exact elements you composed (not a parallel data
+ * shape) so `Navigation.Item`'s active state and `asChild` composition
+ * behave identically in both places.
+ */
+function NavigationRoot({ children, ariaLabel = "Primary navigation", className }: NavigationRootProps) {
+  const [mobileOpen, setMobileOpen] = React.useState(false);
+
+  const items = React.Children.toArray(children);
+  const brand = items.find((child) => React.isValidElement(child) && child.type === NavigationBrand);
+  const rest = items.filter((child) => child !== brand);
+
+  return (
+    <header className="bg-background/95 supports-backdrop-filter:bg-background/60 sticky top-0 z-50 flex w-full justify-center border-b px-4 backdrop-blur">
+      <nav
+        className={cn("flex min-h-14 w-full max-w-7xl items-center justify-between gap-6", className)}
+        aria-label={ariaLabel}
+      >
+        <div className="flex min-w-0 items-center">{brand}</div>
+
+        <div className="ml-auto hidden min-w-0 items-center gap-6 sm:flex">{rest}</div>
+
+        <div className="ml-auto flex items-center sm:hidden">
+          <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
+            <SheetTrigger asChild>
+              <Button
+                variant="outline"
+                size="icon"
+                aria-label={mobileOpen ? "Close menu" : "Open menu"}
+              >
+                <Menu className="size-4" aria-hidden="true" />
+              </Button>
+            </SheetTrigger>
+            <SheetContent>
+              <SheetTitle className="sr-only">Navigation menu</SheetTitle>
+              <div className="mt-8 flex flex-1 flex-col gap-4">
+                <MobileMenuContext.Provider value={true}>{rest}</MobileMenuContext.Provider>
+              </div>
+            </SheetContent>
+          </Sheet>
+        </div>
+      </nav>
+    </header>
+  );
 }
 
-export interface AppNavigationProps {
-  brand?: React.ReactNode;
-  brandHref?: string;
-  endContent?: React.ReactNode;
-  links?: AppNavigationLink[];
-  cta?: AppNavigationCta;
-  ariaLabel?: string;
-  /** Current pathname used to highlight the active link. */
-  activeHref?: string;
+export interface NavigationBrandProps {
+  children: ReactNode;
+  className?: string;
 }
 
-interface NavigationLinkOwnProps {
-  active?: boolean;
-  brand?: boolean;
+/** Always visible, at every viewport width — compose your own link/logo markup directly. */
+function NavigationBrand({ children, className }: NavigationBrandProps) {
+  return <div className={cn("flex items-center font-semibold", className)}>{children}</div>;
 }
 
-export type NavigationLinkProps = NavigationLinkOwnProps &
-  Omit<ComponentPropsWithoutRef<"a">, keyof NavigationLinkOwnProps>;
+export interface NavigationListProps {
+  children: ReactNode;
+  className?: string;
+}
 
-function NavigationLink({
-  children,
-  active = false,
-  brand = false,
-  className,
-  ...props
-}: NavigationLinkProps) {
+/** Semantic `<ul>` of `Navigation.Item`s. Lays out horizontally on desktop, stacks inside the mobile Sheet. */
+function NavigationList({ children, className }: NavigationListProps) {
+  const isMobile = React.useContext(MobileMenuContext);
   return (
-    <a
-      {...props}
+    <ul
       className={cn(
-        "inline-flex h-9 max-h-9 shrink-0 items-center px-3 py-2 text-sm font-medium",
-        !brand && "hover:bg-muted hover:text-muted-foreground",
+        "flex items-center gap-1",
+        isMobile && "flex-col items-stretch gap-1",
         className,
       )}
-      aria-current={active ? "page" : undefined}
     >
       {children}
-    </a>
+    </ul>
   );
 }
 
-function NavigationCta({ href, label }: AppNavigationCta) {
-  return (
-    <Button asChild size="md">
-      <a href={href}>{label}</a>
-    </Button>
-  );
+interface NavigationItemOwnProps {
+  active?: boolean;
+  /** Apply the item styling to a single child (e.g. your router's `Link`) instead of rendering an `<a>`. */
+  asChild?: boolean;
 }
 
-function NavigationRoot({
-  brand,
-  brandHref = "/",
-  endContent,
-  links,
-  cta,
-  ariaLabel = "Primary navigation",
-  activeHref,
-}: AppNavigationProps) {
-  const [mobileOpen, setMobileOpen] = React.useState(false);
+export type NavigationItemProps = NavigationItemOwnProps &
+  Omit<ComponentPropsWithoutRef<"a">, keyof NavigationItemOwnProps>;
+
+/** A single nav link, wrapped in `<li>`. Auto-closes the mobile Sheet on click when rendered there. */
+function NavigationItem({ active = false, asChild = false, className, children, ...props }: NavigationItemProps) {
+  const isMobile = React.useContext(MobileMenuContext);
+  const itemClassName = cn(
+    "inline-flex h-9 max-h-9 shrink-0 items-center px-3 py-2 text-sm font-medium hover:bg-muted hover:text-muted-foreground data-[active]:font-semibold data-[active]:text-foreground",
+    className,
+  );
 
-  const isActive = (href: string) => {
-    if (!activeHref) return false;
-    if (href === activeHref) return true;
-    // Nested routes (e.g. /work/123) keep the parent link active.
-    return href !== "/" && activeHref.startsWith(`${href}/`);
-  };
+  const content = asChild ? (
+    <Slot
+      {...props}
+      data-active={active || undefined}
+      aria-current={active ? "page" : undefined}
+      className={itemClassName}
+    >
+      {children}
+    </Slot>
+  ) : (
+    <a
+      {...props}
+      data-active={active || undefined}
+      aria-current={active ? "page" : undefined}
+      className={itemClassName}
+    >
+      {children}
+    </a>
+  );
+
+  return <li>{isMobile ? <SheetClose asChild>{content}</SheetClose> : content}</li>;
+}
+
+export interface NavigationActionProps {
+  children: ReactNode;
+  className?: string;
+}
 
+/**
+ * Layout wrapper for a CTA, avatar menu, theme toggle, etc. — bring your
+ * own `Button`, no dedicated CTA component needed. Content here does not
+ * auto-close the mobile Sheet on click (it may hold more than one
+ * element, or non-navigational controls) — use `Navigation.Item` instead
+ * for a link that should close the menu when tapped.
+ */
+function NavigationAction({ children, className }: NavigationActionProps) {
+  const isMobile = React.useContext(MobileMenuContext);
   return (
-    <header className="bg-background/95 supports-backdrop-filter:bg-background/60 sticky top-0 z-50 flex w-full justify-center border-b px-4 backdrop-blur">
-      <nav className="w-full max-w-7xl" aria-label={ariaLabel}>
-        <div className="flex min-h-14 items-center justify-between gap-6">
-          <div className="flex min-w-0 items-center">
-            {brand && (
-              <NavigationLink href={brandHref} brand>
-                {brand}
-              </NavigationLink>
-            )}
-          </div>
-
-          <div className="ml-auto hidden min-w-0 items-center gap-1 sm:flex">
-            {links?.map((link) => (
-              <NavigationLink key={link.href} href={link.href} active={isActive(link.href)}>
-                {link.label}
-              </NavigationLink>
-            ))}
-            {cta && <NavigationCta {...cta} />}
-            {endContent}
-          </div>
-
-          <div className="ml-auto flex items-center sm:hidden">
-            <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
-              <SheetTrigger asChild>
-                <Button
-                  variant="outline"
-                  size="icon"
-                  aria-label={mobileOpen ? "Close menu" : "Open menu"}
-                >
-                  <Menu className="size-4" aria-hidden="true" />
-                </Button>
-              </SheetTrigger>
-              <SheetContent>
-                <SheetTitle className="sr-only">Navigation menu</SheetTitle>
-
-                <div className="mt-8 flex flex-1 flex-col gap-1">
-                  {links?.map((link) => (
-                    <SheetClose asChild key={link.href}>
-                      <NavigationLink href={link.href} active={isActive(link.href)}>
-                        {link.label}
-                      </NavigationLink>
-                    </SheetClose>
-                  ))}
-                </div>
-
-                {(cta || endContent) && (
-                  <div className="flex flex-col gap-4 border-t pt-4">
-                    {cta && (
-                      <SheetClose asChild>
-                        <NavigationCta {...cta} />
-                      </SheetClose>
-                    )}
-                    {endContent && <div className="flex items-center gap-3">{endContent}</div>}
-                  </div>
-                )}
-              </SheetContent>
-            </Sheet>
-          </div>
-        </div>
-      </nav>
-    </header>
+    <div
+      className={cn(
+        "flex items-center gap-3",
+        isMobile && "mt-2 flex-col items-stretch gap-3 border-t pt-4",
+        className,
+      )}
+    >
+      {children}
+    </div>
   );
 }
 
 type NavigationComponent = typeof NavigationRoot & {
-  Link: typeof NavigationLink;
+  Brand: typeof NavigationBrand;
+  List: typeof NavigationList;
+  Item: typeof NavigationItem;
+  Action: typeof NavigationAction;
 };
 
 export const Navigation: NavigationComponent = Object.assign(NavigationRoot, {
-  Link: NavigationLink,
+  Brand: NavigationBrand,
+  List: NavigationList,
+  Item: NavigationItem,
+  Action: NavigationAction,
 });
 
 /** @deprecated Use `Navigation` instead. */

package/src/components/navigation/index.ts

@@ -1,9 +1,10 @@
 export { AppNavigation, Navigation } from "./app-navigation";
 export type {
-  AppNavigationCta,
-  AppNavigationLink,
-  AppNavigationProps,
-  NavigationLinkProps,
+  NavigationActionProps,
+  NavigationBrandProps,
+  NavigationItemProps,
+  NavigationListProps,
+  NavigationRootProps,
 } from "./app-navigation";
 export { PaginationControls } from "./pagination-controls";
 export type { PaginationControlsProps } from "./pagination-controls";

package/src/lib/slot.tsx

@@ -0,0 +1,29 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import type { ReactElement } from "react";
+import * as React from "react";
+
+export interface SlotProps extends React.HTMLAttributes<HTMLElement> {
+  children?: React.ReactNode;
+}
+
+/**
+ * Generic `asChild` primitive: merges the props it receives onto its single
+ * child instead of rendering its own DOM element. Lets compound components
+ * (e.g. `Navigation.Item`) apply base styling/aria wiring to whatever the
+ * app renders — a router `Link`, a plain `<a>`, anything — without the app
+ * passing a component as a prop; it's composed as JSX children instead.
+ *
+ * Uses `mergeProps` (already a dependency via `@base-ui/react`) so
+ * event handlers chain instead of one overwriting the other, and
+ * `className`/`style` merge instead of replacing.
+ */
+export const Slot = React.forwardRef<HTMLElement, SlotProps>(({ children, ...props }, ref) => {
+  if (!React.isValidElement(children)) return null;
+  const child = children as ReactElement<Record<string, unknown>>;
+  const merged = mergeProps<"div">(
+    props as React.ComponentPropsWithRef<"div">,
+    child.props as React.ComponentPropsWithRef<"div">,
+  );
+  return React.cloneElement(child, { ...merged, ref } as Record<string, unknown>);
+});
+Slot.displayName = "Slot";