@fayz-ai/ui 0.6.0 → 0.6.6

package/dist/layout/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkGE6XUREM_cjs = require('../chunk-GE6XUREM.cjs');
+var chunkDJHS2XRW_cjs = require('../chunk-DJHS2XRW.cjs');
 var chunkW4XXXJRW_cjs = require('../chunk-W4XXXJRW.cjs');
 require('../chunk-VVVZO2LE.cjs');
 
@@ -8,67 +8,67 @@ require('../chunk-VVVZO2LE.cjs');
 
 Object.defineProperty(exports, "AppShell", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.AppShell; }
+  get: function () { return chunkDJHS2XRW_cjs.AppShell; }
 });
 Object.defineProperty(exports, "BackStyleProvider", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.BackStyleProvider; }
+  get: function () { return chunkDJHS2XRW_cjs.BackStyleProvider; }
 });
 Object.defineProperty(exports, "ICON_MAP", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.ICON_MAP; }
+  get: function () { return chunkDJHS2XRW_cjs.ICON_MAP; }
 });
 Object.defineProperty(exports, "ModuleLayoutProvider", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.ModuleLayoutProvider; }
+  get: function () { return chunkDJHS2XRW_cjs.ModuleLayoutProvider; }
 });
 Object.defineProperty(exports, "ModulePage", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.ModulePage; }
+  get: function () { return chunkDJHS2XRW_cjs.ModulePage; }
 });
 Object.defineProperty(exports, "NavTransitionProvider", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.NavTransitionProvider; }
+  get: function () { return chunkDJHS2XRW_cjs.NavTransitionProvider; }
 });
 Object.defineProperty(exports, "PageHeaderActions", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.PageHeaderActions; }
+  get: function () { return chunkDJHS2XRW_cjs.PageHeaderActions; }
 });
 Object.defineProperty(exports, "PageTransition", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.PageTransition; }
+  get: function () { return chunkDJHS2XRW_cjs.PageTransition; }
 });
 Object.defineProperty(exports, "Sidebar", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.Sidebar; }
+  get: function () { return chunkDJHS2XRW_cjs.Sidebar; }
 });
 Object.defineProperty(exports, "SubpageHeader", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.SubpageHeader; }
+  get: function () { return chunkDJHS2XRW_cjs.SubpageHeader; }
 });
 Object.defineProperty(exports, "Topbar", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.Topbar; }
+  get: function () { return chunkDJHS2XRW_cjs.Topbar; }
 });
 Object.defineProperty(exports, "useBackStyle", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.useBackStyle; }
+  get: function () { return chunkDJHS2XRW_cjs.useBackStyle; }
 });
 Object.defineProperty(exports, "useModuleHeaderActionsSlot", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.useModuleHeaderActionsSlot; }
+  get: function () { return chunkDJHS2XRW_cjs.useModuleHeaderActionsSlot; }
 });
 Object.defineProperty(exports, "useModuleHeaderSlot", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.useModuleHeaderSlot; }
+  get: function () { return chunkDJHS2XRW_cjs.useModuleHeaderSlot; }
 });
 Object.defineProperty(exports, "useModuleLayout", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.useModuleLayout; }
+  get: function () { return chunkDJHS2XRW_cjs.useModuleLayout; }
 });
 Object.defineProperty(exports, "useNavTransition", {
   enumerable: true,
-  get: function () { return chunkGE6XUREM_cjs.useNavTransition; }
+  get: function () { return chunkDJHS2XRW_cjs.useNavTransition; }
 });
 Object.defineProperty(exports, "SaveBar", {
   enumerable: true,

package/dist/layout/index.d.ts

@@ -1,4 +1,4 @@
-export { AppShell, type AppShellProps, type AppShellUser } from './AppShell';
+export { AppShell, type AppShellProps, type AppShellUser, type BottomNavItem, type BottomNavRouteItem, type BottomNavActionItem, type MobileHeaderVariant, } from './AppShell';
 export { Sidebar, type SidebarProps, type SidebarUser, type NavigationItem, ICON_MAP } from './Sidebar';
 export { Topbar, type TopbarProps } from './Topbar';
 export { ModulePage, SubpageHeader, ModuleLayoutProvider, useModuleLayout, PageHeaderActions, BackStyleProvider, useBackStyle, type ModulePageProps, type ModuleNavItem, type ModuleNavVariant, type SubpageHeaderProps, type BackButtonStyle, } from './ModulePage';

package/dist/layout/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layout/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACvG,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EACL,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC1G,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layout/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACvG,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EACL,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC1G,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAA"}

package/dist/layout/index.js

@@ -1,4 +1,4 @@
-export { AppShell, BackStyleProvider, ICON_MAP, ModuleLayoutProvider, ModulePage, NavTransitionProvider, PageHeaderActions, PageTransition, Sidebar, SubpageHeader, Topbar, useBackStyle, useModuleHeaderActionsSlot, useModuleHeaderSlot, useModuleLayout, useNavTransition } from '../chunk-CZ6X6PZT.js';
+export { AppShell, BackStyleProvider, ICON_MAP, ModuleLayoutProvider, ModulePage, NavTransitionProvider, PageHeaderActions, PageTransition, Sidebar, SubpageHeader, Topbar, useBackStyle, useModuleHeaderActionsSlot, useModuleHeaderSlot, useModuleLayout, useNavTransition } from '../chunk-LO5QZO7F.js';
 export { SaveBar, SaveBarProvider, useBackHandler, useSaveBar } from '../chunk-E526FHZ4.js';
 import '../chunk-DNYVEOAX.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fayz-ai/ui",
-  "version": "0.6.0",
+  "version": "0.6.6",
   "description": "Fayz SDK UI — Radix + Tailwind component library with CRUD engine and layout shells",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -81,8 +81,8 @@
     "sonner": "^1.5.0",
     "tailwind-merge": "^2.4.0",
     "zustand": "^4.5.0",
-    "@fayz-ai/core": "^0.6.0",
-    "@fayz-ai/auth": "^0.6.0"
+    "@fayz-ai/core": "^0.6.6",
+    "@fayz-ai/auth": "^0.6.6"
   },
   "devDependencies": {
     "@types/react": "^18.3.0",
@@ -96,9 +96,6 @@
     "typescript": "^5.5.0"
   },
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap --noEmit false",
     "dev": "tsup --watch",

package/src/dashboard/DashboardCanvas.tsx

@@ -90,6 +90,10 @@ export interface DashboardCanvasProps {
   showHeader?: boolean
   /** App-level curation of which widgets show, their order and span. */
   appLayout?: DashboardLayoutConfig
+  /** App-level widgets injected into this surface's grid without a plugin — e.g.
+   *  an "Ask the assistant" CTA. Merged with the registry widgets, then laid out
+   *  (respects each widget's span/defaultOrder). Filtered to this surface. */
+  extraWidgets?: DashboardWidgetDef[]
   /** Show a shared time-range control (sticky, top-right). Widgets read it via
    *  useDashboardRange(). Pass `true` for defaults or an options object. */
   range?: boolean | DashboardRangeOptions
@@ -115,11 +119,18 @@ export interface DashboardRangeOptions {
 }
 
 export function DashboardCanvas({
-  surface, domain, title, subtitle, showHeader = true, appLayout, range,
+  surface, domain, title, subtitle, showHeader = true, appLayout, extraWidgets, range,
   customizable = true, customizeLabel, initialVisibility, onNavigate, className,
 }: DashboardCanvasProps) {
   const runtime = usePluginRuntime()
-  const widgets = getDashboardWidgets(runtime, { surface, domain })
+  const registryWidgets = getDashboardWidgets(runtime, { surface, domain })
+  const widgets = React.useMemo<DashboardWidgetDef[]>(() => {
+    const extra = (extraWidgets ?? []).filter((w) => {
+      if (!(w.surfaces ?? ['home', 'plugin-home']).includes(surface)) return false
+      return !domain || w.domain === domain
+    })
+    return extra.length ? [...registryWidgets, ...extra] : registryWidgets
+  }, [registryWidgets, extraWidgets, surface, domain])
   const rangeOpts: DashboardRangeOptions | null = range ? (range === true ? {} : range) : null
 
   const forceAll = (initialVisibility ?? (surface === 'plugin-home' ? 'all' : 'default')) === 'all'

package/src/dashboard/GoldCard.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react'
+import { cn } from '../utils/cn'
+
+export interface GoldCardProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Brand-colored hero variant — `bg-primary text-primary-foreground` with a
+   * soft branded shadow. Use for the headline card (e.g. a balance hero). When
+   * false (default) it's a plain surface card (`bg-card` + border).
+   */
+  branded?: boolean
+}
+
+/**
+ * GoldCard — a generic, reusable rounded card wrapper for dashboard surfaces.
+ *
+ * The `branded` variant paints the card in the app's primary color so a single
+ * hero (balance, headline KPI, CTA) pops against the neutral grid. Both variants
+ * are internally full-width so they reflow cleanly inside the responsive
+ * DashboardGrid (full-width on mobile, cell-width on desktop).
+ */
+export const GoldCard = React.forwardRef<HTMLDivElement, GoldCardProps>(
+  ({ branded = false, className, children, ...rest }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'h-full rounded-3xl p-5',
+        branded
+          ? 'bg-primary text-primary-foreground shadow-lg shadow-primary/20'
+          : 'border border-border bg-card text-card-foreground shadow-sm',
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  ),
+)
+GoldCard.displayName = 'GoldCard'

package/src/dashboard/KpiCard.tsx

@@ -222,8 +222,10 @@ export function KpiCard(props: KpiCardProps) {
   }
 
   return (
-    <Card>
-      <CardContent className="p-4">
+    // h-full so cards fill the (stretch) grid cell and every card in a row matches
+    // the tallest — labels/subtitles of different lengths no longer misalign them.
+    <Card className="h-full">
+      <CardContent className="flex h-full flex-col p-4">
         <div className="mb-2 flex items-center justify-between gap-2">
           <span className="text-sm text-muted-foreground">{label}</span>
           <span className="text-muted-foreground">{renderIcon(icon)}</span>

package/src/dashboard/index.ts

@@ -10,6 +10,7 @@ export { resolveDashboardLayout, type LaidOutWidget } from './layout'
 export { useDashboardPreferences, type DashboardPreferencesState } from './preferences'
 export { DashboardCustomizeMenu, type DashboardCustomizeMenuProps } from './DashboardCustomizeMenu'
 export { DashboardGrid, type DashboardGridItem, type DashboardGridProps } from './DashboardGrid'
+export { GoldCard, type GoldCardProps } from './GoldCard'
 export {
   DashboardRangeProvider,
   DashboardRangeControl,

package/src/index.ts

@@ -105,6 +105,10 @@ export {
   AppShell,
   type AppShellProps,
   type AppShellUser,
+  type BottomNavItem,
+  type BottomNavRouteItem,
+  type BottomNavActionItem,
+  type MobileHeaderVariant,
   Sidebar,
   type SidebarProps,
   type SidebarUser,
@@ -179,6 +183,8 @@ export {
   DashboardGrid,
   type DashboardGridItem,
   type DashboardGridProps,
+  GoldCard,
+  type GoldCardProps,
   DashboardRangeProvider,
   DashboardRangeControl,
   useDashboardRange,

package/src/layout/AppShell.tsx

@@ -1,5 +1,18 @@
 import * as React from 'react'
-import { Menu } from 'lucide-react'
+import {
+  Menu,
+  Home,
+  Receipt,
+  ArrowLeftRight,
+  Calendar,
+  CreditCard,
+  Settings,
+  MessageCircle,
+  Wallet,
+  PiggyBank,
+  Plus,
+  type LucideIcon,
+} from 'lucide-react'
 import { Sidebar, type NavigationItem, type SidebarUser, type SidebarProps } from './Sidebar'
 import { Topbar } from './Topbar'
 import { SaveBar, SaveBarProvider } from './SaveBar'
@@ -35,6 +48,41 @@ export interface AppShellUser {
   email: string
 }
 
+// ---------------------------------------------------------------------------
+// Bottom-nav item model
+//
+// Two kinds share the mobile tab bar:
+//  - route  (default): a normal tab that navigates to `route`.
+//  - action: a NON-route item rendered as a raised, elevated circular center
+//    button (Mobills style). It fires `onBottomNavAction(id)` instead of
+//    navigating — e.g. a global quick-add "+".
+// ---------------------------------------------------------------------------
+
+export interface BottomNavRouteItem {
+  kind?: 'route'
+  label: string
+  icon: string
+  route: string
+}
+
+export interface BottomNavActionItem {
+  kind: 'action'
+  /** Identifier passed to onBottomNavAction. */
+  id: string
+  icon: string
+  /** Optional accessible label. */
+  label?: string
+}
+
+export type BottomNavItem = BottomNavRouteItem | BottomNavActionItem
+
+/** Mobile header treatment (small screens, <md). Desktop is unaffected.
+ *  - 'minimal'     : a small top header bar (the default / today's behavior).
+ *  - 'transparent' : NO header bar; content is edge-to-edge with a floating
+ *                    profile avatar pinned top-right (calls onProfile).
+ *  - 'hidden'      : no header bar and no floating avatar. */
+export type MobileHeaderVariant = 'transparent' | 'minimal' | 'hidden'
+
 export interface AppShellProps {
   /** Layout variant */
   variant: 'sidebar' | 'topbar' | 'minimal'
@@ -58,7 +106,11 @@ export interface AppShellProps {
   topbarEnd?: React.ReactNode
   sidebarTopContent?: React.ReactNode
   sidebarFooterContent?: React.ReactNode
-  bottomNav?: Array<{ label: string; icon: string; route: string }>
+  bottomNav?: BottomNavItem[]
+  /** Fired when a bottom-nav `action` item (e.g. the center "+") is tapped. */
+  onBottomNavAction?: (id: string) => void
+  /** Mobile header treatment (<md). Default: 'minimal'. Desktop unaffected. */
+  mobileHeader?: MobileHeaderVariant
   /** Rendered in sidebar bottom user slot */
   userMenuSlot?: React.ReactNode
   /** Rendered in sidebar bottom notification slot */
@@ -93,6 +145,8 @@ function SidebarLayout({
   userMenuSlot,
   notificationSlot,
   unreadCount = 0,
+  hasBottomNav = false,
+  mobileHeader = 'minimal',
 }: {
   navigation?: NavigationItem[]
   logo?: React.ReactNode
@@ -115,6 +169,11 @@ function SidebarLayout({
   userMenuSlot?: React.ReactNode
   notificationSlot?: React.ReactNode
   unreadCount?: number
+  /** When a mobile bottom-nav bar is present, the mobile hamburger is
+   *  suppressed so the bottom nav is the primary mobile navigation. */
+  hasBottomNav?: boolean
+  /** Mobile header treatment (<md). Desktop keeps its top bar untouched. */
+  mobileHeader?: MobileHeaderVariant
 }) {
   const sidebarCollapsed = useLayoutStore((s) => s.sidebarCollapsed)
   const setSidebarCollapsed = useLayoutStore((s) => s.setSidebarCollapsed)
@@ -126,7 +185,13 @@ function SidebarLayout({
     <SaveBarProvider>
     <ModuleHeaderSlotContext.Provider value={headerSlot}>
     <ModuleHeaderActionsSlotContext.Provider value={actionsSlot}>
-    <div className="flex h-screen overflow-hidden bg-background">
+    <div className={cn(
+      'flex h-screen overflow-hidden bg-background',
+      // Frame mode: the inset gap around the framed card takes the sidebar (menu)
+      // color, so the white card reads as a panel floating on the same tone as the
+      // left menu. The card's own md:m-2 margin reveals this behind it.
+      frame && 'md:bg-sidebar',
+    )}>
       {/* Desktop Sidebar — always flush / full-height (GoHighLevel style) */}
       <div className="hidden md:flex">
         <Sidebar
@@ -158,16 +223,27 @@ function SidebarLayout({
         'relative flex flex-1 flex-col overflow-hidden',
         frame && 'md:m-2 md:rounded-xl md:border md:border-border md:bg-card'
       )}>
-        {/* Top bar — mobile hamburger + module header slot (title + sub-nav) + actions */}
-        <div className="flex min-h-14 shrink-0 items-center justify-between gap-3 border-b border-border bg-card px-4 py-2">
+        {/* Top bar — mobile hamburger + module header slot (title + sub-nav) + actions.
+            On mobile the bar is suppressed for the 'transparent' / 'hidden' header
+            treatments (content goes edge-to-edge); desktop keeps it always. The
+            portal targets below stay mounted (display:none on mobile) so module
+            pages can still portal their sub-nav on desktop without crashing. */}
+        <div className={cn(
+          'flex min-h-14 shrink-0 items-center justify-between gap-3 border-b border-border bg-card px-4 py-2',
+          mobileHeader !== 'minimal' && 'hidden md:flex',
+        )}>
           <div className="flex min-w-0 flex-1 items-center gap-3">
-            <button
-              onClick={() => setMobileMenuOpen(true)}
-              className="inline-flex items-center justify-center rounded-md p-2 text-muted-foreground hover:bg-accent md:hidden"
-              aria-label="Open menu"
-            >
-              <Menu className="h-5 w-5" />
-            </button>
+            {/* Mobile hamburger — suppressed when a bottom-nav bar owns mobile
+                navigation (mobile-first apps). Desktop sidebar is untouched. */}
+            {!hasBottomNav && (
+              <button
+                onClick={() => setMobileMenuOpen(true)}
+                className="inline-flex items-center justify-center rounded-md p-2 text-muted-foreground hover:bg-accent md:hidden"
+                aria-label="Open menu"
+              >
+                <Menu className="h-5 w-5" />
+              </button>
+            )}
             {pageTitle && <h2 className="font-semibold text-lg">{pageTitle}</h2>}
             {topbarStart}
             {/* Module pages (tabs variant) portal their sub-nav here */}
@@ -181,7 +257,7 @@ function SidebarLayout({
         </div>
 
         {/* Page content */}
-        <main className="flex-1 overflow-y-auto">
+        <main className="flex-1 overflow-y-auto pb-16 md:pb-0">
           {children}
         </main>
 
@@ -236,6 +312,7 @@ function TopbarLayout({
   currentPath,
   topbarStart,
   topbarEnd,
+  hasBottomNav = false,
 }: {
   navigation?: NavigationItem[]
   logo?: React.ReactNode
@@ -251,6 +328,9 @@ function TopbarLayout({
   currentPath?: string
   topbarStart?: React.ReactNode
   topbarEnd?: React.ReactNode
+  /** When a mobile bottom-nav bar is present, the mobile hamburger is
+   *  suppressed so the bottom nav is the primary mobile navigation. */
+  hasBottomNav?: boolean
 }) {
   const [mobileMenuOpen, setMobileMenuOpen] = React.useState(false)
 
@@ -271,10 +351,12 @@ function TopbarLayout({
         userMenuExtras={userMenuExtras}
         leftContent={topbarStart}
         rightContent={topbarEnd}
-        onMenuClick={() => setMobileMenuOpen(true)}
+        onMenuClick={hasBottomNav ? undefined : () => setMobileMenuOpen(true)}
       />
-      {/* Frame inset/border only from md up, so mobile stays edge-to-edge. */}
-      <main className={cn('flex-1 overflow-y-auto', frame && 'md:p-2')}>
+      {/* Frame inset/border only from md up, so mobile stays edge-to-edge. The
+          inset gap behind the framed card is the header color (bg-sidebar), so the
+          white card reads as a panel floating on the same navy as the topbar. */}
+      <main className={cn('flex-1 overflow-y-auto pb-16 md:pb-0', frame && 'md:bg-sidebar md:p-2')}>
         <div className={cn('min-h-full', frame && 'md:rounded-xl md:border md:border-border md:bg-card')}>
           {children}
         </div>
@@ -345,7 +427,7 @@ function MinimalLayout({
         </div>
         {headerEnd && <div className="flex items-center gap-2">{headerEnd}</div>}
       </header>
-      <main className="flex-1 overflow-y-auto">
+      <main className="flex-1 overflow-y-auto pb-16 md:pb-0">
         {children}
       </main>
     </div>
@@ -426,6 +508,111 @@ function MobileOverlay({ onClose, onNavigate, ...sidebarProps }: MobileOverlayPr
   )
 }
 
+// ---------------------------------------------------------------------------
+// Mobile bottom tab bar — rendered for every variant on small screens.
+// ui must NOT import from saas, so the icon lookup is a small local map (a
+// mirror of the saas icon convention). Unknown icon names fall back to Home.
+// ---------------------------------------------------------------------------
+
+const BOTTOM_NAV_ICONS: Record<string, LucideIcon> = {
+  Home,
+  Receipt,
+  ArrowLeftRight,
+  Calendar,
+  CreditCard,
+  Settings,
+  Menu,
+  MessageCircle,
+  Wallet,
+  PiggyBank,
+  Plus,
+}
+
+// Floating profile avatar — mobile-only (md:hidden), pinned top-right over the
+// content. Used with the 'transparent' mobile header treatment so there is no
+// header bar but the user still has a one-tap route into their profile.
+function FloatingProfileAvatar({ user, onClick }: { user?: AppShellUser; onClick?: () => void }) {
+  if (!user) return null
+  const label = user.fullName || user.email
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label="Profile"
+      className="fixed right-3 top-3 z-40 md:hidden"
+    >
+      {user.avatarUrl ? (
+        <img
+          src={user.avatarUrl}
+          alt=""
+          className="h-9 w-9 rounded-full object-cover shadow-md ring-2 ring-background"
+        />
+      ) : (
+        <span className="flex h-9 w-9 items-center justify-center rounded-full bg-primary text-sm font-semibold text-primary-foreground shadow-md ring-2 ring-background">
+          {(label || '?').charAt(0).toUpperCase()}
+        </span>
+      )}
+    </button>
+  )
+}
+
+function MobileBottomNav({
+  items,
+  currentPath,
+  onNavigate,
+  onAction,
+}: {
+  items: NonNullable<AppShellProps['bottomNav']>
+  currentPath?: string
+  onNavigate?: (route: string) => void
+  onAction?: (id: string) => void
+}) {
+  const path = currentPath ?? ''
+  return (
+    <nav className="fixed inset-x-0 bottom-0 z-50 flex h-16 items-center justify-around border-t border-border bg-background md:hidden">
+      {items.map((item) => {
+        // Elevated center ACTION button (Mobills style) — raised above the bar,
+        // circular, primary-filled; fires onBottomNavAction instead of routing.
+        if (item.kind === 'action') {
+          const ActionIcon = BOTTOM_NAV_ICONS[item.icon] ?? Plus
+          return (
+            <div key={item.id} className="flex flex-1 items-start justify-center">
+              <button
+                type="button"
+                onClick={() => onAction?.(item.id)}
+                aria-label={item.label ?? 'Add'}
+                className="-mt-6 flex h-14 w-14 items-center justify-center rounded-full bg-primary text-primary-foreground shadow-lg shadow-primary/30 ring-4 ring-background transition-transform active:scale-95"
+              >
+                <ActionIcon className="h-6 w-6" />
+              </button>
+            </div>
+          )
+        }
+        const isActive =
+          item.route === '/'
+            ? path === '/' || path === ''
+            : path === item.route || path.startsWith(item.route + '/')
+        const Icon = BOTTOM_NAV_ICONS[item.icon] ?? Home
+        return (
+          <button
+            key={item.route}
+            type="button"
+            onClick={() => onNavigate?.(item.route)}
+            className={cn(
+              'flex flex-1 flex-col items-center justify-center gap-0.5 px-1 py-1 transition-colors',
+              isActive ? 'text-primary' : 'text-muted-foreground',
+            )}
+            aria-current={isActive ? 'page' : undefined}
+          >
+            <Icon className="h-5 w-5" />
+            <span className="text-xs">{item.label}</span>
+          </button>
+        )
+      })}
+    </nav>
+  )
+}
+
 // ---------------------------------------------------------------------------
 // AppShell — main entry point
 // ---------------------------------------------------------------------------
@@ -450,13 +637,32 @@ export function AppShell({
   topbarEnd,
   sidebarTopContent,
   sidebarFooterContent,
+  bottomNav,
+  onBottomNavAction,
+  mobileHeader = 'minimal',
   userMenuSlot,
   notificationSlot,
   unreadCount = 0,
 }: AppShellProps) {
+  const hasBottomNav = !!bottomNav?.length
+  const bottomBar = hasBottomNav ? (
+    <MobileBottomNav
+      items={bottomNav!}
+      currentPath={currentPath}
+      onNavigate={onNavigate}
+      onAction={onBottomNavAction}
+    />
+  ) : null
+  // Transparent mobile header → no bar, a floating avatar top-right instead.
+  const floatingAvatar =
+    mobileHeader === 'transparent' && user ? (
+      <FloatingProfileAvatar user={user} onClick={onProfile} />
+    ) : null
+
+  let layoutElement: React.ReactNode
   switch (variant) {
     case 'sidebar':
-      return (
+      layoutElement = (
         <SidebarLayout
           navigation={navigation}
           logo={logo}
@@ -478,13 +684,16 @@ export function AppShell({
           userMenuSlot={userMenuSlot}
           notificationSlot={notificationSlot}
           unreadCount={unreadCount}
+          hasBottomNav={hasBottomNav}
+          mobileHeader={mobileHeader}
         >
           {children}
         </SidebarLayout>
       )
+      break
 
     case 'topbar':
-      return (
+      layoutElement = (
         <TopbarLayout
           navigation={navigation}
           logo={logo}
@@ -499,21 +708,32 @@ export function AppShell({
           currentPath={currentPath}
           topbarStart={topbarStart}
           topbarEnd={topbarEnd}
+          hasBottomNav={hasBottomNav}
         >
           {children}
         </TopbarLayout>
       )
+      break
 
     case 'minimal':
-      return (
+      layoutElement = (
         <MinimalLayout logo={logo} user={user} headerEnd={topbarEnd}>
           {children}
         </MinimalLayout>
       )
+      break
 
     default: {
       const _exhaustive: never = variant
       return null
     }
   }
+
+  return (
+    <>
+      {layoutElement}
+      {floatingAvatar}
+      {bottomBar}
+    </>
+  )
 }

package/src/layout/ModulePage.tsx

@@ -139,7 +139,7 @@ function MobileTabs({ nav }: { nav: ModuleNavItem[] }) {
 
   return (
     <div className="md:hidden -mx-1 mb-4 no-print">
-      <div ref={scrollRef} className="flex gap-1 px-1 pb-2 overflow-x-auto scrollbar-hide">
+      <div ref={scrollRef} className="flex gap-1 px-1 pb-2 overflow-x-auto scrollbar-none">
         {nav.map((item) => {
           const Icon = item.icon ? (ICON_MAP[item.icon] ?? null) : null
           const hasChildren = item.children && item.children.length > 0
@@ -340,7 +340,7 @@ function ModuleHeader({ nav }: { nav: ModuleNavItem[] }) {
 
   const content = (
     <div className="flex w-full min-w-0 items-center gap-4">
-      <div className="flex min-w-0 items-center gap-0.5 overflow-x-auto scrollbar-hide">
+      <div className="flex min-w-0 items-center gap-0.5 overflow-x-auto scrollbar-none">
         {nav.map((item) => {
           const Icon = item.icon ? (ICON_MAP[item.icon] ?? null) : null
           const hasChildren = item.children && item.children.length > 0