@olwiba/ui 0.2.21 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/ui",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -41,7 +41,7 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@olwiba/dx": "0.0.20",
+    "@olwiba/dx": "0.0.23",
     "@tanstack/react-table": "^8.21.3",
     "clsx": "^2.1.1",
     "lucide-react": "^0.562.0",
@@ -63,8 +63,8 @@
   },
   "devDependencies": {
     "@content-collections/mdx": "^0.2.2",
-    "@olwiba/cn": "0.1.26",
-    "@olwiba/docs": "0.1.38",
+    "@olwiba/cn": "0.1.35",
+    "@olwiba/docs": "0.1.40",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-router": "1.154.8",
     "@tanstack/react-router-devtools": "1.154.8",

package/src/app/AppFooter.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import type { HTMLAttributes, ReactNode } from 'react';
+import { cn } from '../lib/utils';
+
+export interface AppFooterProps extends HTMLAttributes<HTMLElement> {
+  /** Leading content — a product line, build info, a rotating message. */
+  start?: ReactNode;
+  /** Trailing content — a status pill, version, or a short link row. */
+  end?: ReactNode;
+}
+
+/**
+ * Quiet utility row for signed-in chrome.
+ *
+ * Pass it to `AppShell`'s `footer` slot: it is app chrome, so it lives beside
+ * the page outlet rather than inside a page pattern. Public marketing pages use
+ * the full `Footer` instead — this exists so long app pages do not end abruptly.
+ *
+ * The row owns geometry only. What the slots contain — live status, version,
+ * links, product copy — stays with the product.
+ */
+export function AppFooter({ start, end, children, className, ...props }: AppFooterProps) {
+  return (
+    <footer
+      {...props}
+      className={cn(
+        'border-t px-4 py-3 text-xs text-muted-foreground sm:px-6',
+        className,
+      )}
+    >
+      <div className="flex min-w-0 items-center justify-between gap-3">
+        <div className="min-w-0 font-medium text-foreground">{start ?? children}</div>
+        {end && <div className="flex shrink-0 items-center gap-2">{end}</div>}
+      </div>
+    </footer>
+  );
+}

package/src/app/AppPageHero.tsx

@@ -12,6 +12,15 @@ export interface AppPageHeroProps {
   action?: ReactNode;
   children?: ReactNode;
   compact?: boolean;
+  /**
+   * How the address is drawn.
+   * - `"card"` (default) — a bordered surface that introduces the route.
+   * - `"plain"` — type only. Use when the page content is itself made of
+   *   surfaces: a second card at the top competes with them instead of
+   *   introducing them, and pushes the region that actually does something
+   *   further down the page.
+   */
+  surface?: 'card' | 'plain';
   className?: string;
 }
 
@@ -29,52 +38,96 @@ export function AppPageHero({
   action,
   children,
   compact = false,
+  surface = 'card',
   className,
 }: AppPageHeroProps) {
+  const isPlain = surface === 'plain';
+
   return (
     <section
       className={cn(
-        'relative overflow-hidden rounded-3xl border bg-card/80 p-5 shadow-sm sm:p-6',
-        // The glow blobs are decoration, and `::after` is the section's last
-        // child — so with everything on `z-index: auto` it paints above the
-        // header content and swallows clicks on whatever sits under it. At
-        // narrow widths the action row stacks below the copy, right into the
-        // bottom-left blob, which is how a visible button stops responding.
-        // pointer-events-none keeps them purely visual.
-        'before:pointer-events-none before:absolute before:-right-16 before:-top-16 before:size-44 before:rounded-full before:bg-primary/15 before:blur-3xl',
-        'after:pointer-events-none after:absolute after:-bottom-20 after:left-10 after:size-52 after:rounded-full after:bg-primary/10 after:blur-3xl',
+        'relative',
+        !isPlain && [
+          'overflow-hidden border bg-card/80 shadow-sm',
+          // Compact is the page-pattern header: same surface and glow, less
+          // bulk, so it introduces a route without eating the fold above dense
+          // content.
+          compact ? 'rounded-2xl p-4 sm:p-5' : 'rounded-3xl p-5 sm:p-6',
+          // The glow blobs are decoration, and `::after` is the section's last
+          // child — so with everything on `z-index: auto` it paints above the
+          // header content and swallows clicks on whatever sits under it. At
+          // narrow widths the action row stacks below the copy, right into the
+          // bottom-left blob, which is how a visible button stops responding.
+          // pointer-events-none keeps them purely visual.
+          'before:pointer-events-none before:absolute before:-right-16 before:-top-16 before:rounded-full before:bg-primary/15 before:blur-3xl',
+          'after:pointer-events-none after:absolute after:left-10 after:rounded-full after:bg-primary/10 after:blur-3xl',
+          compact
+            ? 'before:size-32 after:-bottom-16 after:size-40'
+            : 'before:size-44 after:-bottom-20 after:size-52',
+        ],
         className,
       )}
     >
-      <div className="relative flex flex-col gap-5 sm:flex-row sm:items-start sm:justify-between">
-        <div className="flex min-w-0 gap-4">
+      <div
+        className={cn(
+          'relative flex flex-col sm:flex-row sm:items-start sm:justify-between',
+          compact ? 'gap-3' : 'gap-5',
+        )}
+      >
+        <div className={cn('flex min-w-0 items-start', compact ? 'gap-3' : 'gap-4')}>
           {Icon && (
-            <div className="flex size-12 shrink-0 items-center justify-center rounded-2xl border bg-background/70 text-primary shadow-sm">
-              <Icon className="size-5" />
+            <div
+              className={cn(
+                'flex shrink-0 items-center justify-center border bg-background/70 text-primary shadow-sm',
+                compact ? 'size-10 rounded-xl' : 'size-12 rounded-2xl',
+              )}
+            >
+              <Icon className={compact ? 'size-4' : 'size-5'} />
             </div>
           )}
-          <div className="min-w-0 space-y-2">
+          <div className={cn('min-w-0', compact ? 'space-y-1' : 'space-y-2')}>
             {eyebrow && (
-              <p className="text-xs font-semibold uppercase tracking-[0.24em] text-primary/80">
+              <p
+                className={cn(
+                  'font-semibold uppercase text-primary/80',
+                  compact
+                    ? 'text-[11px] tracking-[0.18em]'
+                    : 'text-xs tracking-[0.24em]',
+                )}
+              >
                 {eyebrow}
               </p>
             )}
             <h1
               className={cn(
-                'font-semibold tracking-tight',
-                compact ? 'text-2xl' : 'text-3xl sm:text-4xl',
+                // Default leading puts ~4px of half-leading above the cap, so
+                // the title reads as sitting low against a top-aligned icon.
+                'font-semibold leading-tight tracking-tight',
+                compact ? 'text-xl sm:text-2xl' : 'text-3xl sm:text-4xl',
               )}
             >
               {title}
             </h1>
             {description && (
-              <p className="max-w-2xl text-sm leading-6 text-muted-foreground">{description}</p>
+              // A div, not a p: `description` is a ReactNode, and callers pass
+              // multiple paragraphs. Nesting <p> inside <p> is invalid HTML and
+              // the parser silently unnests it, which breaks hydration.
+              <div
+                className={cn(
+                  'max-w-2xl text-muted-foreground',
+                  compact ? 'text-sm leading-5' : 'text-sm leading-6',
+                )}
+              >
+                {description}
+              </div>
             )}
           </div>
         </div>
-        {action && <div className="relative shrink-0 sm:pt-1">{action}</div>}
+        {action && (
+          <div className={cn('relative shrink-0', !compact && 'sm:pt-1')}>{action}</div>
+        )}
       </div>
-      {children && <div className="relative mt-5">{children}</div>}
+      {children && <div className={cn('relative', compact ? 'mt-4' : 'mt-5')}>{children}</div>}
     </section>
   );
 }

package/src/app/AppShell.tsx

@@ -84,18 +84,41 @@ export type AppShellRenderLink = (props: {
   className?: string;
 }) => ReactNode;
 
+/**
+ * One step in the header location trail. A bare string is a plain label; give
+ * it an `href` to make it walkable. The final crumb is the current route and is
+ * never rendered as a link.
+ */
+export type AppShellBreadcrumb = string | { label: string; href?: string };
+
 export interface AppShellProps {
   brand?: AppShellBrand;
   navItems?: AppNavItem[];
   /** Primary CTA rendered above nav (e.g. "New project", "Quick create") */
   action?: AppShellAction;
   user?: AppShellUser;
-  /** Text shown in the top header bar */
+  /**
+   * Location context shown in the top header bar. This is app chrome, not the
+   * page address — the page (or its page pattern) owns the `<h1>`. Repeating
+   * the page title here prints the same words twice on every route.
+   */
   pageTitle?: string;
+  /**
+   * Where the current route sits in the app, e.g.
+   * `[{ label: "Admin", href: "/admin" }, "Users"]`. Rendered as a muted trail
+   * and preferred over `pageTitle` when supplied.
+   */
+  breadcrumbs?: AppShellBreadcrumb[];
   /** Slot rendered at the start of the top header bar, after the sidebar trigger. */
   headerStart?: ReactNode;
   /** Slot rendered at the end of the top header bar. */
   headerEnd?: ReactNode;
+  /**
+   * App chrome rendered after the page outlet — normally an `AppFooter`. This
+   * belongs to the shell, not to a page pattern: otherwise every route
+   * re-declares it and height-filling pages fight it for the remaining space.
+   */
+  footer?: ReactNode;
   /** Override link rendering for SPA navigation. Defaults to a native <a>. */
   renderLink?: AppShellRenderLink;
   children?: ReactNode;
@@ -206,7 +229,7 @@ function NavUser({ user }: { user: AppShellUser }) {
                 <AvatarFallback className="text-white" style={identityTint}>
                   <BirdIcon
                     aria-hidden
-                    className="size-4 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
+                    className="size-5 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
                   />
                 </AvatarFallback>
               </Avatar>
@@ -232,7 +255,7 @@ function NavUser({ user }: { user: AppShellUser }) {
                   <AvatarFallback className="text-white" style={identityTint}>
                     <BirdIcon
                       aria-hidden
-                      className="size-4 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
+                      className="size-5 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
                     />
                   </AvatarFallback>
                 </Avatar>
@@ -431,13 +454,29 @@ function ShellSidebar({
 
 function ShellHeader({
   pageTitle,
+  breadcrumbs,
   headerStart,
   headerEnd,
+  renderLink,
 }: {
-  pageTitle: string;
+  pageTitle?: string;
+  breadcrumbs?: AppShellBreadcrumb[];
   headerStart?: ReactNode;
   headerEnd?: ReactNode;
+  renderLink: AppShellRenderLink;
 }) {
+  // App chrome states location, the page states its own name. This used to be
+  // an <h1>, which meant every page rendering its own heading shipped two of
+  // them and printed the same words twice.
+  const source: AppShellBreadcrumb[] = breadcrumbs?.length
+    ? breadcrumbs
+    : pageTitle
+      ? [pageTitle]
+      : [];
+  const trail = source.map((crumb) =>
+    typeof crumb === 'string' ? { label: crumb, href: undefined } : crumb,
+  );
+
   return (
     <header className="flex h-12 shrink-0 items-center gap-2 border-b transition-[width,height] ease-linear group-has-data-[collapsible=icon]/sidebar-wrapper:h-12">
       <div className="flex w-full items-center gap-1 px-4 lg:gap-2 lg:px-6">
@@ -447,8 +486,50 @@ function ShellHeader({
             {headerStart}
           </div>
         )}
-        <Separator orientation="vertical" className="mx-2 data-[orientation=vertical]:h-4" />
-        <h1 className="text-base font-medium">{pageTitle}</h1>
+        {trail.length > 0 && (
+          <>
+            <Separator orientation="vertical" className="mx-2 data-[orientation=vertical]:h-4" />
+            <nav aria-label="Breadcrumb" className="flex min-w-0 items-center gap-1.5 text-sm">
+              {trail.map((crumb, index) => {
+                const isCurrent = index === trail.length - 1;
+                // The last crumb is where you already are, so it stays inert
+                // even when the consumer hands it an href.
+                const isLink = !isCurrent && Boolean(crumb.href);
+
+                return (
+                  <span
+                    className="flex min-w-0 items-center gap-1.5"
+                    key={`${crumb.label}-${index}`}
+                  >
+                    {index > 0 && (
+                      <span aria-hidden="true" className="text-muted-foreground/60">
+                        /
+                      </span>
+                    )}
+                    {isLink ? (
+                      renderLink({
+                        href: crumb.href as string,
+                        className:
+                          'truncate rounded-sm text-muted-foreground transition-colors hover:text-foreground hover:underline underline-offset-4 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                        children: crumb.label,
+                      })
+                    ) : (
+                      <span
+                        aria-current={isCurrent ? 'page' : undefined}
+                        className={cn(
+                          'truncate',
+                          isCurrent ? 'font-medium text-foreground' : 'text-muted-foreground',
+                        )}
+                      >
+                        {crumb.label}
+                      </span>
+                    )}
+                  </span>
+                );
+              })}
+            </nav>
+          </>
+        )}
         {headerEnd && (
           <div className="ml-auto flex items-center gap-1">
             {headerEnd}
@@ -482,7 +563,9 @@ export function AppShell({
   navItems = [],
   action,
   user = defaultUser,
-  pageTitle = 'Dashboard',
+  pageTitle,
+  breadcrumbs,
+  footer,
   headerStart,
   headerEnd,
   renderLink = defaultRenderLink,
@@ -510,8 +593,26 @@ export function AppShell({
         sidebarPosition={sidebarPosition}
       />
       <SidebarInset className="overflow-y-auto">
-        <ShellHeader pageTitle={pageTitle} headerStart={headerStart} headerEnd={headerEnd} />
-        <div className={contentClassName}>{children}</div>
+        <ShellHeader
+          pageTitle={pageTitle}
+          breadcrumbs={breadcrumbs}
+          headerStart={headerStart}
+          headerEnd={headerEnd}
+          renderLink={renderLink}
+        />
+        {/* The shell owns the height chain so routes never have to reconstruct
+            it. `grow` fills the shell on a short page, which settles the footer
+            at the bottom; `shrink-0` with an auto basis means a long page keeps
+            its intrinsic height and scrolls instead of spilling over the
+            footer. `flex flex-col` + `min-h-0` is what lets a route opt into
+            filling the leftover height with `flex-1` on its own root.
+
+            This cannot be left to the consumer: a route passing `flex-1` here
+            gets basis 0, which ignores content height entirely. */}
+        <div className={cn('flex min-h-0 grow shrink-0 flex-col', contentClassName)}>
+          {children}
+        </div>
+        {footer && <div className="shrink-0">{footer}</div>}
       </SidebarInset>
     </SidebarProvider>
   );

package/src/app/UpdateBanner.tsx

@@ -105,20 +105,20 @@ export function UpdateBanner({
       >
         <Card
           className={cn(
-            'max-w-3xl border-amber-300/60 bg-amber-50 dark:border-amber-700/60 dark:bg-amber-950',
+            'max-w-3xl border-border bg-card text-card-foreground shadow-lg',
             className,
           )}
         >
           <div className="flex items-center justify-between gap-6 p-4">
             <div className="flex items-center gap-3">
-              <Sparkles className="size-5 shrink-0 text-amber-600 dark:text-amber-400" aria-hidden="true" />
-              <p className="text-sm text-amber-800 dark:text-amber-200">{message}</p>
+              <Sparkles className="size-5 shrink-0 text-primary" aria-hidden="true" />
+              <p className="text-sm text-card-foreground">{message}</p>
             </div>
             <Button
               onClick={handleRefresh}
               disabled={refreshing}
               size="sm"
-              className="shrink-0 bg-amber-600 text-white hover:bg-amber-700 dark:bg-amber-600 dark:hover:bg-amber-700"
+              className="shrink-0"
             >
               {refreshing ? <RefreshCw className="size-4 animate-spin" /> : buttonLabel}
             </Button>

package/src/index.ts

@@ -26,11 +26,14 @@ export {
   type AppShellUser,
   type AppShellAction,
   type AppShellRenderLink,
+  type AppShellBreadcrumb,
   type AppNavItem,
 } from './app/AppShell';
 
 export { AppPageHero, type AppPageHeroProps } from './app/AppPageHero';
 
+export { AppFooter, type AppFooterProps } from './app/AppFooter';
+
 export {
   AuthSection,
   type AuthSectionProps,