@vvedantb/ui 0.37.1 → 0.38.0

package/README.md

@@ -324,7 +324,7 @@ import {
       rail={
         <SidebarRail
           showDivider={hasPanel && !(isDesktop && collapsed)}
-          top={<RailTile asChild label="Home" active={isHome}><Link to="/"><IconHome size={22} /></Link></RailTile>}
+          top={<RailTile asChild app="vmem" label="Home" active={isHome}><Link to="/" /></RailTile>}
           bodyClassName="scrollbar-thin"
           footerClassName="border-t border-separator"
           footer={<SidebarAccountMenu name={name} email={email} imageUrl={avatarUrl}><DropdownMenuItem>Settings</DropdownMenuItem></SidebarAccountMenu>}
@@ -344,7 +344,8 @@ import {
 - `AppShell`: `sidebar`, `children`, `panelHidden` (main offsets by the rail width instead of the sidebar width), `skipLinkLabel` (`"Skip to main content"`), `mainId` (`"main-content"`), `className`, `mainClassName`, `contentClassName`.
 - `AppSidebar`: legacy (still supported) `rail`, `panel` and `mobile*` props; compose `Sidebar.*` instead. `rail`, `panel` (not rendered while `panelHidden`), `collapsed`, `panelHidden`, `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `id` (default from `useId`), `asideProps` (`data-*` attributes for the `<aside>`), `className`, `mobileTitle`, `mobileHeaderActions` (0.5.2; trailing actions such as icon buttons, in place of the end spacer), `mobileMenuIcon` (`(open) => node`, default a menu icon), `mobileMenuLabel` (`"Open navigation menu"`), `closeLabel` (`"Close navigation"`). Swipe left or Escape closes the drawer. The drawer is `inert` while closed on mobile, and closes when `isDesktop` becomes `true`. Close it on route change in the app. The mobile header is a three-column grid, so the title and trailing actions stay on one row and a long title truncates (0.5.4).
 - `SidebarRail`: legacy (still supported) `top`, `footer`, `bodyAsChild`, `tabs` and `*ClassName` props; compose `Sidebar.Rail` parts instead. `top`, `children` (scroll body), `footer`, `showDivider`, `bodyAsChild` (the single child, for example a tabs list, becomes the body), `className`, `topClassName`, `bodyClassName`, `footerClassName`. Other HTML attributes (`id`, `data-*`, `aria-*`) go to the root `<div>`. The top and footer wrappers render only when their slot is set.
-- `RailTile`: `label` (`aria-label` and tooltip), `active`, `tooltip`, `showTooltip` (default `true`), `badge` (inside the tile, after the children; style it with `railBadgeClass`), `asChild`, `className`. Without `asChild` it is a native `<button type="button">` (0.5.3), so icons keep their authored size; other props go to it. With `asChild` the child (for example a router link) gets the tile classes and `aria-current="page"` when active.
+- `RailTile`: `label` (`aria-label` and tooltip), `active`, `tooltip`, `showTooltip` (default `true`), `badge` (inside the tile, after the children; style it with `railBadgeClass`), `asChild`, `app`, `className`. Without `asChild` it is a native `<button type="button">` (0.5.3), so icons keep their authored size; other props go to it. With `asChild` the child (for example a router link) gets the tile classes and `aria-current="page"` when active.
+- Rail app icon: the home `RailTile` icon is 26px across the apps, enforced by the tile. Pass `app="vmem"` (any `ProductAppName`) and the tile renders `APP_ICONS[app]` at `SIDEBAR_RAIL_APP_ICON_SIZE` (`26`). With `asChild` it goes inside the child (`<Link to="/" />`); without it, `children` are ignored. Tiles without `app` are unchanged: the tile renders the icon you pass, at its size. `Sidebar.MobileHeader` is the standard mobile bar: 56px plus safe-area, solid `bg-surface`, centred `text-base font-semibold tracking-tight` title, 20px menu icon.
 - `RailDivider`, `SidebarIconTooltip` (`label`, `enabled`, `side` `"right"`, `sideOffset` 8).
 - `SidebarPanel`: legacy (still supported) `headerTrailing`, `onClose`, `closeLabel` and `closeButtonClassName`; compose `Sidebar.Panel` parts instead. `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
 - `SidebarAccountMenu`: legacy (still supported) `badge`, `triggerProps`, `contentProps` and `stackedLabel`; compose `Sidebar.Account*` parts instead. `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
@@ -477,7 +478,7 @@ Convention: compound parts are static members of a namespace object, `<Namespace
 | `ResizeHandle` | `SidebarResizeHandle` in a resizable `AppShell`, shown on desktop while the panel shows. Place it inside `Aside`. |
 | `Rail` | Rail column. `showDivider`. |
 | `RailHeader` / `RailBody` / `RailFooter` | Top block, scroll body (`asChild`, `tabs` for a Radix tabs list) and bottom block. `Footer` is an alias of `RailFooter`. |
-| `RailItem` | Rail tile with tooltip (`RailTile`): `label`, `active`, `tooltip`, `showTooltip`, `badge`, `asChild`, `tabValue`. |
+| `RailItem` | Rail tile with tooltip (`RailTile`): `label`, `active`, `tooltip`, `showTooltip`, `badge`, `asChild`, `app`, `tabValue`. |
 | `RailSeparator` | Short rule between rail items (`RailDivider`). |
 | `Tooltip` | Right-side icon tooltip (`SidebarIconTooltip`). |
 | `Panel` | Panel column. `collapsed` (`md:hidden`) and `panelHidden` (renders nothing) default to the Root values. |
@@ -896,6 +897,34 @@ Constants: `landingShellClass`, `landingPanelClass`, `landingItemVariants`, and
 for the footer's `actions` slot `landingFooterLinkClass` (a text link) and
 `landingFooterButtonClass` (a `Button variant="link"`).
 
+### `SiteHeader`
+
+Marketing header (0.38.0): `AppWordmark` at `SITE_HEADER_WORDMARK_SIZE` (20px, icon 28px; no size prop), up to four
+links from `md`, one CTA and an optional GitHub button. Below `md` the links, the CTA and GitHub sit in one full-width
+dropdown menu, in that order. It is plain markup with no motion and needs no `createLandingKit`.
+
+```tsx
+<SiteHeader
+  app="vmem"
+  homeLabel="vmem home"
+  links={[{ label: "Features", href: "#features" }, { label: "Pricing", href: "#pricing" }]}
+  cta={<Button size="sm" className="rounded-full">Sign in</Button>}
+  githubUrl="https://github.com/vvedantb"
+/>
+```
+
+| Prop | |
+| --- | --- |
+| `app` | `vibot`, `vmem`, `verve`, `velth` or `vhub`. |
+| `homeLabel` | `aria-label` of the home wordmark link. |
+| `homeHref` | Default `#home`. |
+| `links` | `{ label, href }[]`, at most 4. More logs a development warning and only the first 4 render. |
+| `cta` | One node. Use `Button` (default variant) with `size="sm"` and `className="rounded-full"`. Shows in the bar from `md` and full width in the menu below. No second slot. |
+| `githubUrl` | Optional. Ghost icon button from `sm`, labelled "{app} on GitHub", and the last menu item. |
+
+The bar is `sticky top-0 z-50`, `h-14 sm:h-16`, `bg-background/80 backdrop-blur-md` with a `border-separator` bottom border.
+`createLandingKit().LandingNav` and `LandingNavMenu` are deprecated in favour of `SiteHeader`.
+
 ### `SiteFooter`
 
 Brand, tagline and social icon buttons; link columns; then copyright, product-of line and legal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one main JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, artifact viewers over the @vvedantb/server artifacts core, native tokens), third-party brand logos (also @vvedantb/ui/logos), motion-driven animated SVG icons (@vvedantb/ui/icons/animated), a client entry without @vvedantb/server, convex or Clerk for Chrome extensions, design-token CSS, shared Tailwind v4 CSS, a Tailwind preset and packaged Instrument Sans fonts.",
   "type": "module",

package/shell/src/SidebarRail.tsx

@@ -3,7 +3,9 @@ import { Slot, Slottable } from "@radix-ui/react-slot";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 import { IconLayoutSidebarLeftCollapse, IconLayoutSidebarLeftExpandFilled } from "@tabler/icons-react";
 import { cn } from "../../src/utils/cn";
-import { railTileClass, railTileStateClass } from "./app-shell-classes";
+import { APP_ICONS } from "../../src/brand/AppIcons";
+import type { ProductAppName } from "../../src/brand/AppWordmark";
+import { SIDEBAR_RAIL_APP_ICON_SIZE, railTileClass, railTileStateClass } from "./app-shell-classes";
 import { SidebarIconTooltip } from "./SidebarIconTooltip";
 
 export type SidebarRailProps = Omit<ComponentPropsWithoutRef<"div">, "children" | "className"> & {
@@ -111,7 +113,7 @@ export function RailFooter({ className, ...props }: SidebarRailFooterProps) {
   return <div {...props} className={cn("flex w-full flex-col items-center gap-1.5 py-3", className)} />;
 }
 
-export type SidebarRailItemProps = Omit<ComponentPropsWithoutRef<"button">, "children"> & {
+type SidebarRailItemBaseProps = Omit<ComponentPropsWithoutRef<"button">, "children"> & {
   /** `aria-label`, and the tooltip unless `tooltip` is set. */
   label: string;
   /** Active state. With `asChild`, also sets `aria-current="page"`. */
@@ -129,9 +131,27 @@ export type SidebarRailItemProps = Omit<ComponentPropsWithoutRef<"button">, "chi
    * The label is sr-only text instead of `aria-label`; `asChild` is ignored.
    */
   tabValue?: string;
-  children: ReactNode;
 };
 
+export type SidebarRailItemProps = SidebarRailItemBaseProps &
+  (
+    | {
+        /**
+         * Product app id for the home tile. The tile renders `APP_ICONS[app]` at
+         * `SIDEBAR_RAIL_APP_ICON_SIZE` (26px), so apps cannot drift. With `asChild` the
+         * icon goes inside the child element (for example `<Link to="/" />`). Without
+         * `asChild`, `children` are ignored.
+         */
+        app: ProductAppName;
+        children?: ReactNode;
+      }
+    | {
+        app?: undefined;
+        /** The tile icon. The caller controls its size. */
+        children: ReactNode;
+      }
+  );
+
 /** Rail tile with a right-side tooltip. Renders a native `<button>`, its child with `asChild`, or a tabs trigger with `tabValue`. */
 export function RailItem({
   label,
@@ -142,9 +162,13 @@ export function RailItem({
   asChild = false,
   tabValue,
   className,
+  app,
   children,
   ...props
 }: SidebarRailItemProps) {
+  const AppIcon = app ? APP_ICONS[app] : null;
+  const appIcon = AppIcon ? <AppIcon size={SIDEBAR_RAIL_APP_ICON_SIZE} /> : null;
+  const content = appIcon ?? children;
   return (
     <SidebarIconTooltip label={tooltip ?? label} enabled={showTooltip}>
       {tabValue !== undefined ? (
@@ -153,7 +177,7 @@ export function RailItem({
           value={tabValue}
           className={cn(railTileClass, "group relative", railTileStateClass(active), className)}
         >
-          {children}
+          {content}
           <span className="sr-only">{label}</span>
           {badge}
         </TabsPrimitive.Trigger>
@@ -164,6 +188,7 @@ export function RailItem({
           aria-current={active ? "page" : undefined}
           className={cn(railTileClass, "group", railTileStateClass(active), className)}
         >
+          {appIcon}
           <Slottable>{children}</Slottable>
           {badge}
         </Slot>
@@ -174,7 +199,7 @@ export function RailItem({
           aria-label={label}
           className={cn(railTileClass, "group", railTileStateClass(active), className)}
         >
-          {children}
+          {content}
           {badge}
         </button>
       )}

package/shell/src/app-shell-classes.ts

@@ -5,6 +5,9 @@ import { cn } from "../../src/utils/cn";
 // accent colour names match that markup and are allow-listed for check:tokens
 // on the marked lines only.
 
+/** App icon size in px for the home `RailTile`. Fixed across the apps. `RailTile` applies it when you pass `app`. */
+export const SIDEBAR_RAIL_APP_ICON_SIZE = 26;
+
 /** Rail tile: size-11, rounded-lg, press scale. */
 export const railTileClass =
   "relative flex size-11 items-center justify-center rounded-lg border active:scale-[0.96] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring";

package/shell/src/index.ts

@@ -46,6 +46,7 @@ export type { SignOutDialogProps } from "./SignOutDialog.js";
 export {
   railBadgeClass,
   railTileClass,
+  SIDEBAR_RAIL_APP_ICON_SIZE,
   railTileStateClass,
   sidebarNavIconClass,
   sidebarNavItemActionsClass,

package/src/client.ts

@@ -257,6 +257,7 @@ export type { SignOutDialogProps } from "../shell/src/SignOutDialog";
 export {
   railBadgeClass,
   railTileClass,
+  SIDEBAR_RAIL_APP_ICON_SIZE,
   railTileStateClass,
   sidebarNavIconClass,
   sidebarNavItemActionsClass,
@@ -313,6 +314,8 @@ export {
   landingPanelClass,
   landingShellClass,
 } from "./marketing/marketing-classes";
+export { SITE_HEADER_WORDMARK_SIZE, SiteHeader } from "./marketing/SiteHeader";
+export type { SiteHeaderLink, SiteHeaderProps } from "./marketing/SiteHeader";
 export type { PricingModalTone, SiteFooterVariant } from "./marketing/marketing-classes";
 export { PROJECT_V_LEGAL_LINKS, PROJECT_V_SOCIALS, SITE_FOOTER_WORDMARK_SIZE, SiteFooter } from "./marketing/SiteFooter";
 export type {

package/src/index.ts

@@ -257,6 +257,7 @@ export type { SignOutDialogProps } from "../shell/src/SignOutDialog";
 export {
   railBadgeClass,
   railTileClass,
+  SIDEBAR_RAIL_APP_ICON_SIZE,
   railTileStateClass,
   sidebarNavIconClass,
   sidebarNavItemActionsClass,
@@ -313,6 +314,8 @@ export {
   landingPanelClass,
   landingShellClass,
 } from "./marketing/marketing-classes";
+export { SITE_HEADER_WORDMARK_SIZE, SiteHeader } from "./marketing/SiteHeader";
+export type { SiteHeaderLink, SiteHeaderProps } from "./marketing/SiteHeader";
 export type { PricingModalTone, SiteFooterVariant } from "./marketing/marketing-classes";
 export { PROJECT_V_LEGAL_LINKS, PROJECT_V_SOCIALS, SITE_FOOTER_WORDMARK_SIZE, SiteFooter } from "./marketing/SiteFooter";
 export type {

package/src/marketing/SiteHeader.tsx

@@ -0,0 +1,128 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { IconMenu2, IconX } from "@tabler/icons-react";
+import { AppWordmark, type ProductAppName } from "../brand/AppWordmark";
+import { GitHubIcon } from "../logos";
+import { Button } from "../ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "../ui/dropdown-menu";
+import { cn } from "../utils/cn";
+import { landingClasses, landingShellClass } from "./marketing-classes";
+
+/** Wordmark text size in px. The icon is `Math.round(20 * 1.4)` = 28px. There is no size prop. */
+export const SITE_HEADER_WORDMARK_SIZE = 20;
+
+const MAX_LINKS = 4;
+
+export type SiteHeaderLink = { label: string; href: string };
+
+export type SiteHeaderProps = {
+  /** Product app id for `AppWordmark`. */
+  app: ProductAppName;
+  /** Home link `href`. Default `#home`. */
+  homeHref?: string;
+  /** `aria-label` of the home wordmark link. */
+  homeLabel: string;
+  /** Up to 4 section links, shown from `md`. More than 4 logs a development warning. */
+  links: readonly SiteHeaderLink[];
+  /**
+   * Exactly one call to action, for example the app's Clerk "Sign in" or "Open <App>" button, or "Get the app".
+   * Pass a `Button` with the default variant, `size="sm"` and `className="rounded-full"`. It shows in the bar from `md`
+   * and below `md` it sits full width in the menu.
+   */
+  cta: ReactNode;
+  /** Optional GitHub URL. An icon button from `sm`, and the last item in the mobile menu. */
+  githubUrl?: string;
+  className?: string;
+};
+
+const focusRing =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background";
+
+function SiteHeaderMenu({ links, cta, githubUrl }: Pick<SiteHeaderProps, "links" | "cta" | "githubUrl">) {
+  const [open, setOpen] = useState(false);
+  const Icon = open ? IconX : IconMenu2;
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" size="icon-sm" aria-label={open ? "Close menu" : "Open menu"} className="md:hidden">
+          <Icon size={20} />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align="end"
+        className="max-h-[70dvh] w-[calc(100vw-2.5rem)] max-w-none overflow-y-auto sm:w-[calc(100vw-4rem)]"
+      >
+        {links.slice(0, MAX_LINKS).map((link) => (
+          <DropdownMenuItem key={link.href} asChild className="max-sm:py-2.5">
+            <a href={link.href}>{link.label}</a>
+          </DropdownMenuItem>
+        ))}
+        <div data-site-header-cta="" className="p-1 [&>*]:w-full">
+          {cta}
+        </div>
+        {githubUrl ? (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem asChild className="max-sm:py-2.5">
+              <a href={githubUrl} target="_blank" rel="noreferrer">
+                <GitHubIcon size={16} />
+                GitHub
+              </a>
+            </DropdownMenuItem>
+          </>
+        ) : null}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/**
+ * Marketing header for the Project V apps: sticky, blurred, `AppWordmark` at `SITE_HEADER_WORDMARK_SIZE`, up to four
+ * links, one `cta` and an optional GitHub button. Below `md` the links, the CTA and GitHub move into one dropdown menu.
+ * Plain markup with no motion, so any app can use it.
+ */
+export function SiteHeader({ app, homeHref = "#home", homeLabel, links, cta, githubUrl, className }: SiteHeaderProps) {
+  const tooMany = links.length > MAX_LINKS;
+  useEffect(() => {
+    if (!tooMany) return;
+    const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV;
+    if (nodeEnv === "production") return;
+    console.warn(`[SiteHeader] SiteHeader supports at most ${MAX_LINKS} links. Received ${links.length}.`);
+  }, [tooMany, links.length]);
+
+  const shown = links.slice(0, MAX_LINKS);
+  return (
+    <header className={cn("sticky top-0 z-50 border-b border-separator bg-background/80 backdrop-blur-md", className)}>
+      <div className={cn(landingShellClass, "flex h-14 items-center justify-between gap-3 sm:h-16")}>
+        <a href={homeHref} className={cn("group min-w-0 shrink-0 rounded-lg", focusRing)} aria-label={homeLabel}>
+          <AppWordmark app={app} size={SITE_HEADER_WORDMARK_SIZE} />
+        </a>
+
+        <nav className="hidden items-center gap-1 md:flex" aria-label="Page">
+          {shown.map((link) => (
+            <a key={link.href} href={link.href} className={landingClasses.navLink}>
+              {link.label}
+            </a>
+          ))}
+        </nav>
+
+        <div className="flex items-center gap-1.5">
+          {githubUrl ? (
+            <Button asChild variant="ghost" size="icon-sm" className="hidden sm:inline-flex">
+              <a href={githubUrl} target="_blank" rel="noreferrer" aria-label={`${app} on GitHub`}>
+                <GitHubIcon size={18} />
+              </a>
+            </Button>
+          ) : null}
+          <div className="hidden md:flex">{cta}</div>
+          <SiteHeaderMenu links={shown} cta={cta} githubUrl={githubUrl} />
+        </div>
+      </div>
+    </header>
+  );
+}

package/src/marketing/createLandingKit.tsx

@@ -153,7 +153,7 @@ export function createLandingKit({ motion }: LandingKitOptions): LandingKit {
     );
   }
 
-  /** Sticky blurred header that rises in on mount. */
+  /** @deprecated Use `SiteHeader`. Sticky blurred header that rises in on mount. */
   function LandingNav({ brand, homeLabel, links, github, actions, menu }: LandingNavProps) {
     return (
       <motion.header