@fayz-ai/ui 0.8.2 → 0.8.3

package/src/layout/AppShell.tsx

@@ -98,6 +98,10 @@ export interface AppShellProps {
   onProfile?: () => void
   onSettings?: () => void
   onBilling?: () => void
+  /** Current-plan pill shown next to the user in the topbar menu. */
+  userPlan?: { label: string; paid: boolean }
+  /** i18n label for the billing/subscription user-menu item. */
+  billingLabel?: string
   pageTitle?: string
   currentPath?: string
   userMenuExtras?: { label: string; icon?: React.ReactNode; onClick: () => void }[]
@@ -117,6 +121,35 @@ export interface AppShellProps {
   notificationSlot?: React.ReactNode
   /** Unread notification count */
   unreadCount?: number
+  /** Optional headings above the sidebar nav sections (contextual sidebars). */
+  sidebarSectionLabels?: { main?: string; secondary?: string; settings?: string }
+  /** Identity of the current sidebar context — changing it animates the rail
+   *  swap as a push (new nav in, previous nav out). */
+  sidebarNavKey?: string
+  /** Push direction for a `sidebarNavKey` change. Default 'forward'. */
+  sidebarNavDirection?: 'forward' | 'back'
+  /**
+   * Full-height column pinned to the right (the assistant dock, a tasks
+   * panel). Rendered as a flex SIBLING of the layout, so the app narrows to
+   * make room instead of being covered — the difference between a split view
+   * and a modal that happens to be tall.
+   *
+   * Falsy renders nothing and costs nothing: no wrapper, no divider, the
+   * layout element stands alone exactly as before.
+   */
+  rightRail?: React.ReactNode
+  /** Whether the rail is showing. Separate from `rightRail` so the column can
+   *  animate its width instead of snapping when it closes. */
+  rightRailOpen?: boolean
+  /** Starting width in px. Ignored once the user drags. Default 380. */
+  defaultRightRailWidth?: number
+  /** Fired after every drag so the host can persist the preference. */
+  onRightRailWidthChange?: (width: number) => void
+  /** Drag bounds in px. Defaults 300 / 720. */
+  rightRailMinWidth?: number
+  rightRailMaxWidth?: number
+  /** Accessible name for the drag handle. */
+  rightRailResizeLabel?: string
 }
 
 // ---------------------------------------------------------------------------
@@ -147,6 +180,9 @@ function SidebarLayout({
   unreadCount = 0,
   hasBottomNav = false,
   mobileHeader = 'minimal',
+  sidebarSectionLabels,
+  sidebarNavKey,
+  sidebarNavDirection,
 }: {
   navigation?: NavigationItem[]
   logo?: React.ReactNode
@@ -174,6 +210,9 @@ function SidebarLayout({
   hasBottomNav?: boolean
   /** Mobile header treatment (<md). Desktop keeps its top bar untouched. */
   mobileHeader?: MobileHeaderVariant
+  sidebarSectionLabels?: AppShellProps['sidebarSectionLabels']
+  sidebarNavKey?: string
+  sidebarNavDirection?: 'forward' | 'back'
 }) {
   const sidebarCollapsed = useLayoutStore((s) => s.sidebarCollapsed)
   const setSidebarCollapsed = useLayoutStore((s) => s.setSidebarCollapsed)
@@ -213,6 +252,9 @@ function SidebarLayout({
           userMenuSlot={userMenuSlot}
           notificationSlot={notificationSlot}
           unreadCount={unreadCount}
+          sectionLabels={sidebarSectionLabels}
+          navKey={sidebarNavKey}
+          navDirection={sidebarNavDirection}
         />
       </div>
 
@@ -257,7 +299,7 @@ function SidebarLayout({
         </div>
 
         {/* Page content */}
-        <main className="flex-1 overflow-y-auto pb-16 md:pb-0">
+        <main className="min-w-0 flex-1 overflow-y-auto pb-16 md:pb-0">
           {children}
         </main>
 
@@ -307,11 +349,15 @@ function TopbarLayout({
   onProfile,
   onSettings,
   onBilling,
+  userPlan,
+  billingLabel,
   userMenuExtras,
+  orgSwitcher,
   frame,
   currentPath,
   topbarStart,
   topbarEnd,
+  notificationSlot,
   hasBottomNav = false,
 }: {
   navigation?: NavigationItem[]
@@ -323,11 +369,17 @@ function TopbarLayout({
   onProfile?: () => void
   onSettings?: () => void
   onBilling?: () => void
+  userPlan?: AppShellProps['userPlan']
+  billingLabel?: AppShellProps['billingLabel']
   userMenuExtras?: AppShellProps['userMenuExtras']
+  /** Workspace switcher — rendered beside the logo (desktop) and in the mobile drawer. */
+  orgSwitcher?: React.ReactNode
   frame?: boolean
   currentPath?: string
   topbarStart?: React.ReactNode
   topbarEnd?: React.ReactNode
+  /** Bell/inbox slot — in the topbar layout it renders with the right-side actions. */
+  notificationSlot?: 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
@@ -348,17 +400,25 @@ function TopbarLayout({
         onProfile={onProfile}
         onSettings={onSettings}
         onBilling={onBilling}
+        userPlan={userPlan}
+        billingLabel={billingLabel}
         userMenuExtras={userMenuExtras}
+        orgSwitcher={orgSwitcher}
         leftContent={topbarStart}
-        rightContent={topbarEnd}
+        rightContent={(topbarEnd || notificationSlot) ? <>{topbarEnd}{notificationSlot}</> : undefined}
         onMenuClick={hasBottomNav ? undefined : () => setMobileMenuOpen(true)}
       />
       {/* 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}
+      {/* The frame is fixed to the viewport and the content scrolls INSIDE it,
+          mirroring SidebarLayout. With `main` as the scroller the card grew with
+          the page and its bottom edge rode off-screen. */}
+      <main className={cn('flex min-w-0 min-h-0 flex-1 flex-col overflow-hidden', frame && 'md:bg-sidebar md:p-2')}>
+        <div className={cn('flex min-w-0 min-h-0 flex-1 flex-col overflow-hidden', frame && 'md:rounded-xl md:border md:border-border md:bg-card')}>
+          <div className="min-h-0 flex-1 overflow-y-auto pb-16 md:pb-0">
+            {children}
+          </div>
         </div>
       </main>
 
@@ -378,6 +438,7 @@ function TopbarLayout({
           onProfile={onProfile}
           onSettings={onSettings}
           onBilling={onBilling}
+          orgSwitcher={orgSwitcher}
           userMenuSlot={user ? <DrawerUserRow user={user} /> : undefined}
           onClose={() => setMobileMenuOpen(false)}
         />
@@ -427,7 +488,7 @@ function MinimalLayout({
         </div>
         {headerEnd && <div className="flex items-center gap-2">{headerEnd}</div>}
       </header>
-      <main className="flex-1 overflow-y-auto pb-16 md:pb-0">
+      <main className="min-w-0 flex-1 overflow-y-auto pb-16 md:pb-0">
         {children}
       </main>
     </div>
@@ -629,6 +690,8 @@ export function AppShell({
   onProfile,
   onSettings,
   onBilling,
+  userPlan,
+  billingLabel,
   pageTitle,
   currentPath,
   userMenuExtras,
@@ -643,6 +706,16 @@ export function AppShell({
   userMenuSlot,
   notificationSlot,
   unreadCount = 0,
+  sidebarSectionLabels,
+  sidebarNavKey,
+  sidebarNavDirection,
+  rightRail,
+  rightRailOpen = true,
+  defaultRightRailWidth,
+  onRightRailWidthChange,
+  rightRailMinWidth,
+  rightRailMaxWidth,
+  rightRailResizeLabel,
 }: AppShellProps) {
   const hasBottomNav = !!bottomNav?.length
   const bottomBar = hasBottomNav ? (
@@ -686,6 +759,9 @@ export function AppShell({
           unreadCount={unreadCount}
           hasBottomNav={hasBottomNav}
           mobileHeader={mobileHeader}
+          sidebarSectionLabels={sidebarSectionLabels}
+          sidebarNavKey={sidebarNavKey}
+          sidebarNavDirection={sidebarNavDirection}
         >
           {children}
         </SidebarLayout>
@@ -703,11 +779,15 @@ export function AppShell({
           onProfile={onProfile}
           onSettings={onSettings}
           onBilling={onBilling}
+          userPlan={userPlan}
+          billingLabel={billingLabel}
           userMenuExtras={userMenuExtras}
+          orgSwitcher={orgSwitcher}
           frame={contentFrame}
           currentPath={currentPath}
           topbarStart={topbarStart}
           topbarEnd={topbarEnd}
+          notificationSlot={notificationSlot}
           hasBottomNav={hasBottomNav}
         >
           {children}
@@ -731,9 +811,177 @@ export function AppShell({
 
   return (
     <>
-      {layoutElement}
+      {rightRail ? (
+        <SplitWithRightRail
+          rail={rightRail}
+          open={rightRailOpen}
+          frame={contentFrame}
+          defaultWidth={defaultRightRailWidth}
+          onWidthChange={onRightRailWidthChange}
+          minWidth={rightRailMinWidth}
+          maxWidth={rightRailMaxWidth}
+          resizeLabel={rightRailResizeLabel}
+        >
+          {layoutElement}
+        </SplitWithRightRail>
+      ) : (
+        layoutElement
+      )}
       {floatingAvatar}
       {bottomBar}
     </>
   )
 }
+
+// ---------------------------------------------------------------------------
+// SplitWithRightRail — the app on the left, a full-height rail on the right,
+// a divider the user owns between them.
+//
+// The layouts all root at `h-screen overflow-hidden`, so putting them in a
+// `flex-1 min-w-0` cell keeps their height and lets them shrink. `min-w-0` is
+// load-bearing: without it a flex child refuses to go below its content width
+// and the rail gets pushed off-screen instead of the content reflowing.
+// ---------------------------------------------------------------------------
+
+function SplitWithRightRail({
+  children,
+  rail,
+  open,
+  frame,
+  defaultWidth = 380,
+  onWidthChange,
+  minWidth = 300,
+  maxWidth = 720,
+  resizeLabel = 'Resize panel',
+}: {
+  children: React.ReactNode
+  rail: React.ReactNode
+  open: boolean
+  /** Frame mode: the gutter between content and rail takes the sidebar tone,
+   *  the same surface the content card floats on. Without this the split shows
+   *  a bare strip of page background and the rail reads as bolted on. */
+  frame?: boolean
+  defaultWidth?: number
+  onWidthChange?: (width: number) => void
+  minWidth?: number
+  maxWidth?: number
+  resizeLabel?: string
+}) {
+  const [width, setWidth] = React.useState(defaultWidth)
+  const [dragging, setDragging] = React.useState(false)
+
+  const clamp = React.useCallback(
+    (value: number) => Math.min(maxWidth, Math.max(minWidth, value)),
+    [minWidth, maxWidth],
+  )
+
+  // The app follows the pointer to the pixel, so the drag runs on window
+  // listeners rather than on the handle: the cursor routinely outruns a 6px
+  // target, and a resize that stops when you move too fast feels broken.
+  React.useEffect(() => {
+    if (!dragging) return
+    const onMove = (event: PointerEvent) => {
+      event.preventDefault()
+      setWidth(clamp(window.innerWidth - event.clientX))
+    }
+    const stop = () => setDragging(false)
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', stop)
+    window.addEventListener('pointercancel', stop)
+    // Text selection across the whole app while dragging a divider is pure
+    // noise, and iframes/canvases would otherwise swallow the pointer.
+    const previousSelect = document.body.style.userSelect
+    const previousCursor = document.body.style.cursor
+    document.body.style.userSelect = 'none'
+    document.body.style.cursor = 'col-resize'
+    return () => {
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', stop)
+      window.removeEventListener('pointercancel', stop)
+      document.body.style.userSelect = previousSelect
+      document.body.style.cursor = previousCursor
+    }
+  }, [dragging, clamp])
+
+  // Report only on release: firing per pointer frame would write to
+  // localStorage ~60×/second for one gesture.
+  React.useEffect(() => {
+    if (dragging) return
+    onWidthChange?.(width)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dragging])
+
+  const nudge = (delta: number) => setWidth((current) => clamp(current + delta))
+
+  return (
+    // Sidebar tone always: the gutter and the divider sit in the shell's
+    // chrome, next to the menu — painting them page-white put a bright strip
+    // between the dark chrome and the rail, which read as a seam rather than
+    // as space.
+    <div className={cn('flex h-screen w-full overflow-hidden bg-sidebar', !frame && 'md:bg-background')}>
+      <div className="min-w-0 flex-1">{children}</div>
+
+      {/* Divider — desktop only; on a phone the rail is a sheet over the app,
+          and there is nothing to divide. */}
+      <div
+        role="separator"
+        aria-orientation="vertical"
+        aria-label={resizeLabel}
+        aria-valuenow={width}
+        aria-valuemin={minWidth}
+        aria-valuemax={maxWidth}
+        tabIndex={0}
+        onPointerDown={(event) => {
+          event.preventDefault()
+          setDragging(true)
+        }}
+        onDoubleClick={() => setWidth(clamp(defaultWidth))}
+        onKeyDown={(event) => {
+          // Keyboard resize: a pointer-only divider makes the split view
+          // unusable for anyone not using a mouse.
+          if (event.key === 'ArrowLeft') { event.preventDefault(); nudge(24) }
+          else if (event.key === 'ArrowRight') { event.preventDefault(); nudge(-24) }
+          else if (event.key === 'Home') { event.preventDefault(); setWidth(maxWidth) }
+          else if (event.key === 'End') { event.preventDefault(); setWidth(minWidth) }
+        }}
+        className={cn(
+          'group relative hidden w-1 shrink-0 cursor-col-resize focus-visible:outline-none',
+          open && 'md:block',
+        )}
+      >
+        {/* Invisible at rest: the gutter's own tone already separates the two
+            panes, and a permanent rule there just adds a line to look at.
+            It appears when you reach for it. */}
+        <span
+          className={cn(
+            'absolute inset-y-6 left-1/2 w-px -translate-x-1/2 rounded-full bg-transparent transition-colors',
+            'group-hover:bg-primary/60 group-focus-visible:bg-primary',
+            dragging && 'bg-primary',
+          )}
+        />
+        {/* Hit area wider than the line: 1px is honest visually and hostile
+            to aim for. */}
+        <span className="absolute inset-y-0 -left-1.5 -right-1.5" />
+      </div>
+
+      {/* Rendered once: two copies would mount the rail's contents twice. On a
+          phone the box collapses to zero width and the rail positions itself
+          `fixed` over the screen. The frame inset is padding HERE rather than
+          margin on the rail — a full-height child plus vertical margins
+          overflows its own box. */}
+      <aside
+        style={{ ['--fayz-rail-w' as string]: `${width}px` }}
+        className={cn(
+          'w-0 shrink-0 overflow-hidden',
+          // Animating WIDTH is what makes the app glide back instead of
+          // snapping; skipped mid-drag so the divider stays glued to the cursor.
+          !dragging && 'motion-safe:transition-[width] motion-safe:duration-200 motion-safe:ease-out',
+          open && 'md:w-[var(--fayz-rail-w)]',
+          frame && 'md:py-2 md:pr-2',
+        )}
+      >
+        {rail}
+      </aside>
+    </div>
+  )
+}

package/src/layout/ModulePage.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react'
 import { createPortal } from 'react-dom'
-import { ChevronDown, ChevronRight, ChevronLeft } from 'lucide-react'
+import { ChevronDown, ChevronRight, ChevronLeft, Crown } from 'lucide-react'
 import { useTranslation } from '@fayz-ai/core'
 import { cn } from '../utils/cn'
 import { ICON_MAP } from './Topbar'
@@ -28,7 +28,31 @@ export interface ModuleNavItem {
   icon?: string
   active?: boolean
   onClick?: () => void
-  children?: { id: string; label: string; active?: boolean; onClick?: () => void }[]
+  /** Feature id for the access gate. When set, `useModuleNavAccess` (in
+   *  @fayz-ai/saas) resolves this link's role (hide) and plan (Crown) state. */
+  feature?: string
+  /** Freemium discovery: the user's role allows this link but their plan does
+   *  not entitle `feature`. Renders a small Crown badge (same vocabulary as the
+   *  Sidebar top-level nav); the click still navigates and the gated CONTENT
+   *  shows the UpgradePrompt. Typically set by `useModuleNavAccess`. */
+  premium?: boolean
+  children?: ModuleNavItem[]
+}
+
+// ---------------------------------------------------------------------------
+// PremiumBadge — the small Crown affordance shared by every module-nav renderer
+// (rail, mobile tabs, GHL header). Same vocabulary as the Sidebar top-level nav
+// so a plan-gated sub-module link reads identically wherever it appears.
+// ---------------------------------------------------------------------------
+
+function PremiumBadge({ className }: { className?: string }) {
+  const t = useTranslation()
+  const tip = t('upgrade.badgeTooltip')
+  return (
+    <span title={tip} aria-label={tip} className={cn('inline-flex shrink-0', className)}>
+      <Crown className="h-3.5 w-3.5 text-amber-500" aria-hidden />
+    </span>
+  )
 }
 
 export interface ModulePageProps {
@@ -92,6 +116,7 @@ function NavItem({ item }: { item: ModuleNavItem }) {
       >
         {Icon && <Icon className="h-4 w-4 shrink-0" />}
         <span className="flex-1 text-left truncate">{item.label}</span>
+        {item.premium && <PremiumBadge className="ml-1" />}
         {hasChildren && (
           expanded
             ? <ChevronDown className="h-3.5 w-3.5 shrink-0 opacity-50" />
@@ -112,7 +137,8 @@ function NavItem({ item }: { item: ModuleNavItem }) {
                   : 'text-muted-foreground hover:text-foreground hover:bg-muted/50'
               )}
             >
-              {child.label}
+              <span className="flex-1 text-left truncate">{child.label}</span>
+              {child.premium && <PremiumBadge className="ml-1" />}
             </button>
           ))}
         </div>
@@ -168,6 +194,7 @@ function MobileTabs({ nav }: { nav: ModuleNavItem[] }) {
             >
               {Icon && <Icon className="h-3 w-3" />}
               {item.label}
+              {item.premium && <PremiumBadge />}
               {hasChildren && <ChevronDown className={cn('h-2.5 w-2.5 transition-transform', isExpanded && 'rotate-180')} />}
             </button>
           )
@@ -193,6 +220,7 @@ function MobileTabs({ nav }: { nav: ModuleNavItem[] }) {
                 )}
               >
                 {child.label}
+                {child.premium && <PremiumBadge />}
               </button>
             ))}
           </div>
@@ -359,6 +387,7 @@ function ModuleHeader({ nav }: { nav: ModuleNavItem[] }) {
             >
               {Icon && <Icon className="h-4 w-4" />}
               {item.label}
+              {item.premium && <PremiumBadge />}
             </button>
           )
         })}