@olwiba/ui 0.2.23 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/ui",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "private": false,
   "type": "module",
   "sideEffects": false,

package/src/app/AppFooter.tsx

@@ -17,15 +17,16 @@ export interface AppFooterProps extends HTMLAttributes<HTMLElement> {
  * 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.
+ * The row owns its solid chrome surface and geometry so page ambience cannot
+ * bleed through it. 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',
+        'border-t bg-background px-4 py-3 text-xs text-muted-foreground sm:px-6',
         className,
       )}
     >

package/src/app/AppShell.tsx

@@ -8,7 +8,6 @@ import {
   CreditCardIcon,
   LogOutIcon,
   MoreVerticalIcon,
-  PlusCircleIcon,
   SettingsIcon,
 } from 'lucide-react';
 import {
@@ -60,6 +59,8 @@ export interface AppShellUser {
   email: string;
   name?: string;
   avatar?: string;
+  /** Product-owned artwork shown when no avatar image exists. Defaults to the Olwiba bird. */
+  avatarFallback?: ReactNode;
   /** Displayed as a sub-label (e.g. plan tier). */
   plan?: string;
   onSignOut?: () => void;
@@ -91,6 +92,13 @@ export type AppShellRenderLink = (props: {
  */
 export type AppShellBreadcrumb = string | { label: string; href?: string };
 
+export interface AppShellHeaderControls {
+  /** Expands the desktop sidebar or opens its native mobile presentation. */
+  expandSidebar: () => void;
+}
+
+export type AppShellHeaderStart = ReactNode | ((controls: AppShellHeaderControls) => ReactNode);
+
 export interface AppShellProps {
   brand?: AppShellBrand;
   navItems?: AppNavItem[];
@@ -109,10 +117,16 @@ export interface AppShellProps {
    * 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 start of the top header bar, after the sidebar trigger.
+   * Use the render form when a custom control needs to expand the shell's own
+   * sidebar without importing its private provider context.
+   */
+  headerStart?: AppShellHeaderStart;
   /** Slot rendered at the end of the top header bar. */
   headerEnd?: ReactNode;
+  /** Product chrome rendered above the user menu in the sidebar footer. */
+  sidebarFooterStart?: ReactNode;
   /**
    * App chrome rendered after the page outlet — normally an `AppFooter`. This
    * belongs to the shell, not to a page pattern: otherwise every route
@@ -135,6 +149,10 @@ export interface AppShellProps {
    * - `"contained"` — fills its parent container; use in docs sandboxes, modals, or embedded previews.
    */
   sidebarPosition?: 'viewport' | 'contained';
+  /** Remount key for an animated sidebar identity or navigation-mode change. */
+  sidebarContentKey?: string;
+  /** Classes applied to the sidebar header, content, and footer. */
+  sidebarContentClassName?: string;
   /** Which side the sidebar sits on. @default "left" */
   side?: 'left' | 'right';
   /**
@@ -227,10 +245,12 @@ function NavUser({ user }: { user: AppShellUser }) {
               <Avatar mode={avatarMode} size="sm">
                 {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
                 <AvatarFallback className="text-white" style={identityTint}>
-                  <BirdIcon
-                    aria-hidden
-                    className="size-5 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
-                  />
+                  {user.avatarFallback ?? (
+                    <BirdIcon
+                      aria-hidden
+                      className="size-5 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
+                    />
+                  )}
                 </AvatarFallback>
               </Avatar>
               <div className="grid flex-1 text-left text-sm leading-tight">
@@ -253,10 +273,12 @@ function NavUser({ user }: { user: AppShellUser }) {
                 <Avatar mode={avatarMode} size="sm">
                   {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
                   <AvatarFallback className="text-white" style={identityTint}>
-                    <BirdIcon
-                      aria-hidden
-                      className="size-5 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
-                    />
+                    {user.avatarFallback ?? (
+                      <BirdIcon
+                        aria-hidden
+                        className="size-5 drop-shadow-[0_1px_1px_rgb(0_0_0/0.3)]"
+                      />
+                    )}
                   </AvatarFallback>
                 </Avatar>
                 <div className="grid flex-1 text-left text-sm leading-tight">
@@ -315,6 +337,9 @@ function ShellSidebar({
   collapsible,
   side,
   sidebarPosition,
+  sidebarContentKey,
+  sidebarContentClassName,
+  sidebarFooterStart,
 }: {
   brand: AppShellBrand;
   navItems: AppNavItem[];
@@ -324,6 +349,9 @@ function ShellSidebar({
   collapsible: 'icon' | 'offcanvas' | 'none';
   side: 'left' | 'right';
   sidebarPosition: 'viewport' | 'contained';
+  sidebarContentKey?: string;
+  sidebarContentClassName?: string;
+  sidebarFooterStart?: ReactNode;
 }) {
   const fallbackLogo = typeof brand.name === 'string' ? brand.name.slice(0, 1).toUpperCase() : null;
   const { isMobile, setOpenMobile } = useSidebar();
@@ -333,7 +361,10 @@ function ShellSidebar({
 
   return (
     <Sidebar side={side} collapsible={collapsible} sidebarPosition={sidebarPosition}>
-      <SidebarHeader className="py-3">
+      <SidebarHeader
+        key={`${sidebarContentKey ?? 'default'}-header`}
+        className={cn('py-3', sidebarContentClassName)}
+      >
         <SidebarMenu>
           <SidebarMenuItem onClickCapture={closeMobileMenu}>
             {/* Not a link, and not a button.
@@ -388,7 +419,10 @@ function ShellSidebar({
         </SidebarMenu>
       </SidebarHeader>
 
-      <SidebarContent>
+      <SidebarContent
+        key={`${sidebarContentKey ?? 'default'}-content`}
+        className={sidebarContentClassName}
+      >
         <SidebarGroup>
           <SidebarGroupContent className="flex flex-col gap-2">
             {action && (
@@ -445,7 +479,11 @@ function ShellSidebar({
         </SidebarGroup>
       </SidebarContent>
 
-      <SidebarFooter>
+      <SidebarFooter
+        key={`${sidebarContentKey ?? 'default'}-footer`}
+        className={sidebarContentClassName}
+      >
+        {sidebarFooterStart}
         <NavUser user={user} />
       </SidebarFooter>
     </Sidebar>
@@ -461,10 +499,18 @@ function ShellHeader({
 }: {
   pageTitle?: string;
   breadcrumbs?: AppShellBreadcrumb[];
-  headerStart?: ReactNode;
+  headerStart?: AppShellHeaderStart;
   headerEnd?: ReactNode;
   renderLink: AppShellRenderLink;
 }) {
+  const { isMobile, setOpen, setOpenMobile } = useSidebar();
+  const expandSidebar = useCallback(() => {
+    if (isMobile) setOpenMobile(true);
+    else setOpen(true);
+  }, [isMobile, setOpen, setOpenMobile]);
+  const headerStartContent =
+    typeof headerStart === 'function' ? headerStart({ expandSidebar }) : headerStart;
+
   // 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.
@@ -481,11 +527,7 @@ function ShellHeader({
     <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">
         <SidebarTrigger className="-ml-1" />
-        {headerStart && (
-          <div className="flex items-center gap-1">
-            {headerStart}
-          </div>
-        )}
+        {headerStartContent && <div className="flex items-center gap-1">{headerStartContent}</div>}
         {trail.length > 0 && (
           <>
             <Separator orientation="vertical" className="mx-2 data-[orientation=vertical]:h-4" />
@@ -530,11 +572,7 @@ function ShellHeader({
             </nav>
           </>
         )}
-        {headerEnd && (
-          <div className="ml-auto flex items-center gap-1">
-            {headerEnd}
-          </div>
-        )}
+        {headerEnd && <div className="ml-auto flex items-center gap-1">{headerEnd}</div>}
       </div>
     </header>
   );
@@ -553,7 +591,9 @@ const defaultUser: AppShellUser = {
 };
 
 const defaultRenderLink: AppShellRenderLink = ({ href, children, className }) => (
-  <a href={href} className={className}>{children}</a>
+  <a href={href} className={className}>
+    {children}
+  </a>
 );
 
 // ─── Main export ──────────────────────────────────────────────────────────────
@@ -571,6 +611,9 @@ export function AppShell({
   renderLink = defaultRenderLink,
   collapsible = 'icon',
   sidebarPosition = 'viewport',
+  sidebarContentKey,
+  sidebarContentClassName,
+  sidebarFooterStart,
   side = 'left',
   contentClassName = 'p-6',
   children,
@@ -591,6 +634,9 @@ export function AppShell({
         collapsible={collapsible}
         side={side}
         sidebarPosition={sidebarPosition}
+        sidebarContentKey={sidebarContentKey}
+        sidebarContentClassName={sidebarContentClassName}
+        sidebarFooterStart={sidebarFooterStart}
       />
       <SidebarInset className="overflow-y-auto">
         <ShellHeader

package/src/app/EmptyState.tsx

@@ -7,28 +7,79 @@ import { cn } from '@olwiba/cn';
 export interface EmptyStateProps extends React.HTMLAttributes<HTMLDivElement> {
   icon?: LucideIcon;
   title: string;
-  description?: string;
+  description?: React.ReactNode;
+  eyebrow?: React.ReactNode;
   action?: React.ReactNode;
+  secondaryAction?: React.ReactNode;
+  /** Adds the application-card surface used for route-level empty states. */
+  variant?: 'plain' | 'card';
+  /** Reduces the card presentation's minimum height and padding. */
+  compact?: boolean;
+  /** Fills a flex-sized parent rather than using a fixed minimum height. */
+  fill?: boolean;
 }
 
-export function EmptyState({ icon: Icon, title, description, action, className, ...props }: EmptyStateProps) {
+export function EmptyState({
+  icon: Icon,
+  title,
+  description,
+  eyebrow,
+  action,
+  secondaryAction,
+  variant = 'plain',
+  compact = false,
+  fill = false,
+  className,
+  ...props
+}: EmptyStateProps) {
+  const card = variant === 'card';
+
   return (
     <div
-      className={cn('flex flex-col items-center justify-center gap-3 py-12 text-center', className)}
+      className={cn(
+        'relative flex flex-col items-center justify-center overflow-hidden text-center',
+        !card && 'gap-3 py-12',
+        card && 'min-h-72 rounded-xl border border-dashed bg-card/80 p-8 shadow-sm sm:p-10',
+        card && compact && 'min-h-0 p-5 sm:p-6',
+        fill && 'min-h-0 w-full flex-1',
+        className,
+      )}
       {...props}
     >
-      {Icon && (
-        <div className="flex h-12 w-12 items-center justify-center rounded-2xl border bg-muted">
-          <Icon className="size-6 text-muted-foreground" />
-        </div>
+      {card && (
+        <div className="pointer-events-none absolute inset-x-10 top-0 h-24 rounded-full bg-primary/10 blur-3xl" />
       )}
-      <div className="space-y-1">
-        <h3 className="font-semibold">{title}</h3>
-        {description && (
-          <p className="max-w-xs text-sm text-muted-foreground">{description}</p>
+      <div className={cn('relative flex flex-col items-center', card ? 'gap-4' : 'gap-3')}>
+        {Icon && (
+          <div
+            className={cn(
+              'flex size-12 items-center justify-center rounded-2xl border',
+              card ? 'bg-background text-primary shadow-sm' : 'bg-muted text-muted-foreground',
+            )}
+          >
+            <Icon className={card ? 'size-5' : 'size-6'} />
+          </div>
+        )}
+        <div className={cn(card ? 'max-w-md space-y-2' : 'max-w-xs space-y-1')}>
+          {eyebrow && (
+            <p className="text-xs font-medium uppercase tracking-[0.2em] text-muted-foreground">
+              {eyebrow}
+            </p>
+          )}
+          <h3 className={cn('font-semibold', card && 'text-xl tracking-tight')}>{title}</h3>
+          {description && (
+            <div className={cn('text-sm text-muted-foreground', card && 'leading-6')}>
+              {description}
+            </div>
+          )}
+        </div>
+        {(action || secondaryAction) && (
+          <div className="flex flex-col items-center gap-3 sm:flex-row">
+            {action}
+            {secondaryAction}
+          </div>
         )}
       </div>
-      {action}
     </div>
   );
 }

package/src/blog/PostList.tsx

@@ -9,7 +9,11 @@ export interface PostListProps {
   posts: PostCardProps[];
   renderLink?: AppShellRenderLink;
   emptyMessage?: string;
-  /** Max columns at the widest breakpoint. */
+  /**
+   * Max columns at the widest breakpoint. When omitted, one- and two-post
+   * collections are balanced automatically instead of leaving an empty third
+   * column.
+   */
   columns?: 2 | 3;
   className?: string;
 }
@@ -18,20 +22,29 @@ export function PostList({
   posts,
   renderLink,
   emptyMessage = 'No posts published yet.',
-  columns = 3,
+  columns,
   className,
 }: PostListProps) {
   if (posts.length === 0) {
-    return (
-      <p className="text-sm text-muted-foreground italic">{emptyMessage}</p>
-    );
+    return <p className="text-sm text-muted-foreground italic">{emptyMessage}</p>;
   }
 
+  const resolvedColumns = columns ?? (posts.length < 3 ? 2 : 3);
+  const balancedShortListClassName =
+    columns === undefined
+      ? posts.length === 1
+        ? 'mx-auto w-full max-w-md sm:grid-cols-1'
+        : posts.length === 2
+          ? 'mx-auto w-full max-w-3xl'
+          : undefined
+      : undefined;
+
   return (
     <div
       className={cn(
         'grid grid-cols-1 gap-x-8 gap-y-14 sm:grid-cols-2',
-        columns === 3 && 'lg:grid-cols-3',
+        resolvedColumns === 3 && 'lg:grid-cols-3',
+        balancedShortListClassName,
         className,
       )}
     >

package/src/components/LoadMore.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import * as React from 'react';
+import { Button, Spinner, cn } from '@olwiba/cn';
+
+export interface LoadMoreProps extends React.HTMLAttributes<HTMLDivElement> {
+  hasNextPage: boolean;
+  isFetchingNextPage: boolean;
+  fetchNextPage: () => void | Promise<unknown>;
+  /** Watches the sentinel instead of showing a manual button. */
+  auto?: boolean;
+  /** Plural noun used by the manual button, for example `properties`. */
+  label?: string;
+  /** Starts loading before the sentinel reaches the viewport. */
+  rootMargin?: string;
+}
+
+/** Cursor-pagination footer with either guarded infinite scroll or a manual fallback. */
+export function LoadMore({
+  hasNextPage,
+  isFetchingNextPage,
+  fetchNextPage,
+  auto = true,
+  label = 'more',
+  rootMargin = '400px',
+  className,
+  ...props
+}: LoadMoreProps) {
+  const sentinelRef = React.useRef<HTMLDivElement>(null);
+  const stateRef = React.useRef({ hasNextPage, isFetchingNextPage, fetchNextPage });
+  stateRef.current = { hasNextPage, isFetchingNextPage, fetchNextPage };
+
+  React.useEffect(() => {
+    if (!auto) return;
+    const node = sentinelRef.current;
+    if (!node) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry?.isIntersecting) return;
+        const state = stateRef.current;
+        if (state.hasNextPage && !state.isFetchingNextPage) void state.fetchNextPage();
+      },
+      { rootMargin },
+    );
+
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [auto, rootMargin]);
+
+  if (!hasNextPage) return null;
+
+  return (
+    <div ref={sentinelRef} className={cn('flex justify-center py-4', className)} {...props}>
+      {auto ? (
+        <span className="flex h-9 items-center text-sm text-muted-foreground" aria-live="polite">
+          {isFetchingNextPage && (
+            <>
+              <Spinner className="mr-2 size-4" /> Loading more…
+            </>
+          )}
+        </span>
+      ) : (
+        <Button
+          variant="outline"
+          onClick={() => void fetchNextPage()}
+          disabled={isFetchingNextPage}
+        >
+          {isFetchingNextPage ? (
+            <>
+              <Spinner className="mr-2 size-4" /> Loading…
+            </>
+          ) : (
+            `Load more ${label}`
+          )}
+        </Button>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -27,6 +27,8 @@ export {
   type AppShellAction,
   type AppShellRenderLink,
   type AppShellBreadcrumb,
+  type AppShellHeaderControls,
+  type AppShellHeaderStart,
   type AppNavItem,
 } from './app/AppShell';
 
@@ -145,6 +147,7 @@ export { CommandMenu, type CommandMenuProps, type CommandMenuGroup, type Command
 
 // ─── Components — data ───────────────────────────────────────────────────────
 export { DataTable, type DataTableProps, type DataTableColumn } from './components/DataTable';
+export { LoadMore, type LoadMoreProps } from './components/LoadMore';
 export { DataView, type DataViewProps } from './app/DataView';
 export { Chart, type ChartProps, type ChartSeries } from './components/Chart';
 export { FileUpload, type FileUploadProps, type FileUploadEntry } from './components/FileUpload';