@fayz-ai/saas 0.1.6

package/src/shell/hooks/useModuleNavigation.ts

@@ -0,0 +1,124 @@
+import { useState, useRef, useCallback, useEffect } from 'react'
+
+/**
+ * Navigation direction for transition animations.
+ * 'forward' = deeper into content (list → detail → edit, or main → settings)
+ * 'back' = returning to parent (edit → detail → list, or settings → main)
+ */
+export type NavDirection = 'forward' | 'back'
+
+/**
+ * View depth mapping — used to determine animation direction.
+ * Higher depth = deeper in the navigation hierarchy.
+ */
+export type DepthMap = Record<string, number>
+
+const DEFAULT_DEPTHS: DepthMap = {
+  summary: 0,
+  list: 0,
+  new: 1,
+  edit: 2,
+  detail: 1,
+  settings: 1,
+}
+
+/**
+ * Reusable module navigation hook for plugins.
+ * Manages view state, hash synchronization, and animation direction.
+ *
+ * @param hashBase — the base hash path for this module (e.g. '/financial')
+ * @param depthMap — optional custom depth mapping for views
+ */
+export function useModuleNavigation(hashBase: string, depthMap?: DepthMap, homeView = 'summary') {
+  const depths = { ...DEFAULT_DEPTHS, ...depthMap }
+
+  function getInitialView(): string {
+    const rawHash = window.location.hash.slice(1) || '/'
+    // Strip query string from hash before parsing segments
+    const hash = rawHash.split('?')[0]
+    if (hash === hashBase || hash === hashBase + '/') return homeView
+    if (hash.startsWith(hashBase + '/settings')) return 'settings'
+    if (hash.startsWith(hashBase + '/')) {
+      const rest = hash.slice(hashBase.length + 1)
+      const segments = rest.split('/')
+      // '/inventory/dashboard' → treat as home view
+      if (segments.length === 1 && segments[0] === homeView) return homeView
+      // Detect action + ID patterns: '/products/edit/uuid' or '/stock/detail/uuid'
+      const ACTION_KEYWORDS = ['edit', 'detail', 'view']
+      if (segments.length >= 3) {
+        const maybeAction = segments[segments.length - 2]
+        if (ACTION_KEYWORDS.includes(maybeAction)) {
+          return segments.slice(0, -2).join('-') + '-' + maybeAction + ':' + segments[segments.length - 1]
+        }
+      }
+      return segments.join('-')
+    }
+    return homeView
+  }
+
+  const [view, setView] = useState(getInitialView)
+  const [direction, setDirection] = useState<NavDirection>('forward')
+  const prevDepthRef = useRef(getDepth(getInitialView()))
+
+  // Sync view from external hash changes (e.g., topbar nav clicking the module link)
+  useEffect(() => {
+    function handler() {
+      const hash = (window.location.hash.slice(1) || '/').split('?')[0]
+      // Only react if the hash is within our module's base
+      if (hash === hashBase || hash === hashBase + '/' || hash.startsWith(hashBase + '/')) {
+        const newView = getInitialView()
+        if (newView !== view) {
+          const nextDepth = getDepth(newView)
+          setDirection(nextDepth > prevDepthRef.current ? 'forward' : 'back')
+          prevDepthRef.current = nextDepth
+          setView(newView)
+        }
+      }
+    }
+    window.addEventListener('hashchange', handler)
+    return () => window.removeEventListener('hashchange', handler)
+  }, [view, hashBase])
+
+  function getDepth(v: string): number {
+    // Check exact match first
+    if (depths[v] !== undefined) return depths[v]
+    // Check base view name (e.g. 'payables-list' → check 'list', 'payables-new' → check 'new')
+    const parts = v.split('-')
+    const suffix = parts[parts.length - 1]
+    if (depths[suffix] !== undefined) return depths[suffix]
+    // Edit with ID (e.g. 'payables-edit:123')
+    if (v.includes('edit')) return depths.edit ?? 2
+    return 0
+  }
+
+  const navigate = useCallback((nextView: string, hash?: string) => {
+    const nextDepth = getDepth(nextView)
+    setDirection(nextDepth > prevDepthRef.current ? 'forward' : 'back')
+    prevDepthRef.current = nextDepth
+    setView(nextView)
+
+    // Sync hash — explicit hash takes priority, otherwise derive from view name
+    if (hash) {
+      window.location.hash = hash
+    } else if (nextView === homeView || nextView === 'summary' || nextView === '') {
+      window.location.hash = hashBase
+    } else {
+      // Convert view name to URL-friendly path: 'payables-list' → '/financial/payables/list'
+      // 'payables-edit:uuid-with-dashes' → '/financial/payables/edit/uuid-with-dashes'
+      const colonIdx = nextView.indexOf(':')
+      if (colonIdx !== -1) {
+        // Has an ID after colon — only convert dashes in the prefix, keep ID intact
+        const prefix = nextView.slice(0, colonIdx).replace(/-/g, '/')
+        const id = nextView.slice(colonIdx + 1)
+        window.location.hash = `${hashBase}/${prefix}/${id}`
+      } else {
+        const path = nextView.replace(/-/g, '/')
+        window.location.hash = `${hashBase}/${path}`
+      }
+    }
+  }, [hashBase])
+
+  const animationClass = direction === 'forward' ? 'saas-nav-forward' : 'saas-nav-back'
+
+  return { view, direction, animationClass, navigate }
+}

package/src/shell/hooks/useNotifications.ts

@@ -0,0 +1,114 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react'
+import { useNotificationStore } from '../stores/notifications.store'
+import { getSupabaseClient } from '../lib/supabase'
+import type { Notification } from '../types'
+
+export function useNotifications() {
+  const store = useNotificationStore()
+  const channelRef = useRef<ReturnType<
+    ReturnType<typeof getSupabaseClient>['channel']
+  > | null>(null)
+
+  const fetchNotifications = useCallback(async () => {
+    store.setLoading(true)
+    try {
+      const supabase = getSupabaseClient()
+      const { data, error } = await supabase
+        .from('notifications')
+        .select('*')
+        .order('created_at', { ascending: false })
+        .limit(50)
+
+      if (error) throw error
+      store.setNotifications(data ?? [])
+    } catch (err) {
+      console.error('Failed to fetch notifications:', err)
+    } finally {
+      store.setLoading(false)
+    }
+  }, [store])
+
+  const markAsRead = useCallback(
+    async (id: string) => {
+      store.markRead(id)
+      try {
+        const supabase = getSupabaseClient()
+        const { error } = await supabase
+          .from('notifications')
+          .update({ read: true })
+          .eq('id', id)
+
+        if (error) throw error
+      } catch (err) {
+        console.error('Failed to mark notification as read:', err)
+      }
+    },
+    [store]
+  )
+
+  const markAllAsRead = useCallback(async () => {
+    store.markAllRead()
+    try {
+      const supabase = getSupabaseClient()
+      const { error } = await supabase
+        .from('notifications')
+        .update({ read: true })
+        .eq('read', false)
+
+      if (error) throw error
+    } catch (err) {
+      console.error('Failed to mark all notifications as read:', err)
+    }
+  }, [store])
+
+  const subscribeToRealtime = useCallback(() => {
+    try {
+      const supabase = getSupabaseClient()
+      const channel = supabase
+        .channel('notifications')
+        .on(
+          'postgres_changes',
+          { event: 'INSERT', schema: 'public', table: 'notifications' },
+          (payload) => {
+            store.addNotification(payload.new as Notification)
+          }
+        )
+        .subscribe()
+
+      channelRef.current = channel
+    } catch (err) {
+      console.error('Failed to subscribe to realtime notifications:', err)
+    }
+  }, [store])
+
+  useEffect(() => {
+    return () => {
+      if (channelRef.current) {
+        const supabase = getSupabaseClient()
+        supabase.removeChannel(channelRef.current)
+        channelRef.current = null
+      }
+    }
+  }, [])
+
+  return useMemo(
+    () => ({
+      notifications: store.notifications,
+      unreadCount: store.unreadCount,
+      loading: store.loading,
+      fetchNotifications,
+      markAsRead,
+      markAllAsRead,
+      subscribeToRealtime,
+    }),
+    [
+      store.notifications,
+      store.unreadCount,
+      store.loading,
+      fetchNotifications,
+      markAsRead,
+      markAllAsRead,
+      subscribeToRealtime,
+    ]
+  )
+}

package/src/shell/hooks/usePermission.ts

@@ -0,0 +1,101 @@
+import { useCallback, useMemo } from 'react'
+import { useTenantStore } from '../stores/tenant.store'
+import { usePermissionsStore } from '../stores/permissions.store'
+import type { MemberRole } from '../types'
+import type { PermissionAction, SystemPermission } from '../types/permissions'
+
+// Legacy role-based permissions (backward compat)
+const PERMISSIONS = [
+  'manage_billing',
+  'manage_members',
+  'manage_settings',
+  'manage_content',
+  'view_content',
+  'view_analytics',
+] as const
+
+export type Permission = (typeof PERMISSIONS)[number]
+
+const ROLE_PERMISSIONS: Record<MemberRole, Permission[]> = {
+  owner: [...PERMISSIONS],
+  admin: PERMISSIONS.filter((p) => p !== 'manage_billing'),
+  manager: ['manage_content', 'view_content', 'view_analytics'],
+  staff: ['view_content'],
+  viewer: ['view_content'],
+}
+
+const ROLE_HIERARCHY: Record<MemberRole, number> = {
+  owner: 5,
+  admin: 4,
+  manager: 3,
+  staff: 2,
+  viewer: 1,
+}
+
+export function usePermission() {
+  const currentRole = useTenantStore((s) => s.currentRole)
+  const currentProfile = usePermissionsStore((s) => s.currentProfile)
+
+  // Profile-based permission check (feature × action matrix)
+  const can = useCallback(
+    (featureId: string, action: PermissionAction): boolean => {
+      if (!currentProfile) return true // no permissions configured = allow all
+      // Owner bypasses all feature checks
+      if (currentProfile.id === 'owner') return true
+      return currentProfile.grants[featureId]?.includes(action) ?? false
+    },
+    [currentProfile],
+  )
+
+  const hasSystemPermission = useCallback(
+    (perm: SystemPermission): boolean => {
+      if (!currentProfile) return true
+      return (currentProfile.systemPermissions ?? []).includes(perm)
+    },
+    [currentProfile],
+  )
+
+  // Legacy role-based permissions
+  const permissions = useMemo<Permission[]>(() => {
+    if (!currentRole) return []
+    return ROLE_PERMISSIONS[currentRole]
+  }, [currentRole])
+
+  const hasPermission = useCallback(
+    (permission: Permission | string): boolean => {
+      // First try profile-based system permissions
+      if (currentProfile) {
+        return (currentProfile.systemPermissions ?? []).includes(permission as SystemPermission)
+      }
+      // Fall back to legacy role-based
+      return permissions.includes(permission as Permission)
+    },
+    [currentProfile, permissions],
+  )
+
+  const requireRole = useCallback(
+    (role: MemberRole): boolean => {
+      if (!currentRole) return false
+      return ROLE_HIERARCHY[currentRole] >= ROLE_HIERARCHY[role]
+    },
+    [currentRole],
+  )
+
+  const canAccess = useCallback(
+    (requiredPermissions: Permission[]): boolean => {
+      return requiredPermissions.every((p) => permissions.includes(p))
+    },
+    [permissions],
+  )
+
+  return {
+    currentRole,
+    currentProfile,
+    permissions,
+    can,
+    hasSystemPermission,
+    hasPermission,
+    requireRole,
+    canAccess,
+  }
+}

package/src/shell/hooks/usePluginPrefs.ts

@@ -0,0 +1,113 @@
+import { useState, useCallback, useMemo } from 'react'
+
+// ---------------------------------------------------------------------------
+// Plugin Preferences — localStorage-backed per-plugin user preferences
+//
+// Usage:
+//   const prefs = usePluginPrefs('agenda', { calendarView: 'timeGridWeek', slotDuration: 30 })
+//   prefs.get('calendarView')             // 'timeGridWeek'
+//   prefs.set('calendarView', 'dayGridMonth')
+//   prefs.getAll()                         // { calendarView: 'dayGridMonth', slotDuration: 30 }
+//   prefs.reset()                          // back to defaults
+//
+// Keys are namespaced: `saas:prefs:{pluginId}` in localStorage.
+// Each plugin gets its own isolated namespace.
+// ---------------------------------------------------------------------------
+
+const STORAGE_PREFIX = 'saas:prefs:'
+
+function readStore<T extends Record<string, unknown>>(pluginId: string, defaults: T): T {
+  try {
+    const raw = localStorage.getItem(STORAGE_PREFIX + pluginId)
+    if (!raw) return { ...defaults }
+    return { ...defaults, ...JSON.parse(raw) }
+  } catch {
+    return { ...defaults }
+  }
+}
+
+function writeStore<T extends Record<string, unknown>>(pluginId: string, data: T): void {
+  try {
+    localStorage.setItem(STORAGE_PREFIX + pluginId, JSON.stringify(data))
+  } catch { /* quota exceeded or private browsing — silently ignore */ }
+}
+
+export interface PluginPrefs<T extends Record<string, unknown>> {
+  /** Get a single preference value */
+  get<K extends keyof T>(key: K): T[K]
+  /** Set a single preference value (persists immediately) */
+  set<K extends keyof T>(key: K, value: T[K]): void
+  /** Update multiple preferences at once */
+  update(partial: Partial<T>): void
+  /** Get all preferences as an object */
+  getAll(): T
+  /** Reset all preferences to defaults */
+  reset(): void
+}
+
+/**
+ * Hook for localStorage-backed plugin preferences.
+ *
+ * @param pluginId  Unique plugin identifier (e.g. 'agenda', 'financial')
+ * @param defaults  Default values — also defines the shape of the prefs object
+ * @returns         PluginPrefs accessor with get/set/update/reset
+ */
+export function usePluginPrefs<T extends Record<string, unknown>>(
+  pluginId: string,
+  defaults: T,
+): PluginPrefs<T> {
+  const [state, setState] = useState<T>(() => readStore(pluginId, defaults))
+
+  const get = useCallback(<K extends keyof T>(key: K): T[K] => {
+    return state[key]
+  }, [state])
+
+  const set = useCallback(<K extends keyof T>(key: K, value: T[K]): void => {
+    setState((prev) => {
+      const next = { ...prev, [key]: value }
+      writeStore(pluginId, next)
+      return next
+    })
+  }, [pluginId])
+
+  const update = useCallback((partial: Partial<T>): void => {
+    setState((prev) => {
+      const next = { ...prev, ...partial }
+      writeStore(pluginId, next)
+      return next
+    })
+  }, [pluginId])
+
+  const getAll = useCallback((): T => state, [state])
+
+  const reset = useCallback((): void => {
+    setState({ ...defaults })
+    writeStore(pluginId, defaults)
+  }, [pluginId, defaults])
+
+  return useMemo(() => ({ get, set, update, getAll, reset }), [get, set, update, getAll, reset])
+}
+
+// ---------------------------------------------------------------------------
+// Non-hook utility for use outside React components (e.g. in store factories)
+// ---------------------------------------------------------------------------
+
+export function getPluginPref<T>(pluginId: string, key: string, defaultValue: T): T {
+  try {
+    const raw = localStorage.getItem(STORAGE_PREFIX + pluginId)
+    if (!raw) return defaultValue
+    const parsed = JSON.parse(raw)
+    return parsed[key] ?? defaultValue
+  } catch {
+    return defaultValue
+  }
+}
+
+export function setPluginPref(pluginId: string, key: string, value: unknown): void {
+  try {
+    const raw = localStorage.getItem(STORAGE_PREFIX + pluginId)
+    const existing = raw ? JSON.parse(raw) : {}
+    existing[key] = value
+    localStorage.setItem(STORAGE_PREFIX + pluginId, JSON.stringify(existing))
+  } catch { /* ignore */ }
+}

package/src/shell/hooks/usePlugins.ts

@@ -0,0 +1,18 @@
+import type { PluginRuntimeContext, PluginWidgetZone, ResolvedPluginWidget } from '../types/plugins'
+import { getWidgetsForZone, usePluginRuntime, usePluginRuntimeOptional } from '../lib/plugins'
+
+export function usePlugins() {
+  return usePluginRuntime()
+}
+
+export function usePluginsOptional() {
+  return usePluginRuntimeOptional()
+}
+
+export function useWidgets(
+  zone: PluginWidgetZone,
+  contextOverrides?: Partial<PluginRuntimeContext>,
+): ResolvedPluginWidget[] {
+  const runtime = usePluginRuntime()
+  return getWidgetsForZone(runtime, zone, contextOverrides) as unknown as ResolvedPluginWidget[]
+}

package/src/shell/hooks/useTenant.ts

@@ -0,0 +1,106 @@
+import { useCallback } from 'react'
+import { getSupabaseClient } from '../lib/supabase'
+import { useTenantStore } from '../stores/tenant.store'
+import type { TenantSettings } from '../types'
+
+export function useTenant() {
+  const store = useTenantStore()
+  const supabase = getSupabaseClient()
+
+  const fetchTenant = useCallback(async (tenantId: string) => {
+    store.setLoading(true)
+    const { data, error } = await supabase
+      .from('tenants')
+      .select('*')
+      .eq('id', tenantId)
+      .single()
+
+    if (error) {
+      store.setLoading(false)
+      throw error
+    }
+
+    store.setTenant({
+      id: data.id,
+      name: data.name,
+      slug: data.slug,
+      logoUrl: data.logo_url,
+      settings: data.settings,
+      plan: data.plan,
+      createdAt: data.created_at,
+      updatedAt: data.updated_at,
+    })
+    store.setLoading(false)
+    return data
+  }, [supabase, store])
+
+  const fetchMembers = useCallback(async () => {
+    if (!store.tenant) throw new Error('No tenant loaded')
+
+    store.setLoading(true)
+    const { data, error } = await supabase
+      .from('tenant_members')
+      .select('*, user:users(id, email, full_name, avatar_url)')
+      .eq('tenant_id', store.tenant.id)
+      .order('joined_at', { ascending: true })
+
+    if (error) {
+      store.setLoading(false)
+      throw error
+    }
+
+    const members = (data ?? []).map((m: any) => ({
+      id: m.id,
+      userId: m.user_id,
+      tenantId: m.tenant_id,
+      role: m.role,
+      user: {
+        id: m.user.id,
+        email: m.user.email,
+        fullName: m.user.full_name,
+        avatarUrl: m.user.avatar_url,
+      },
+      joinedAt: m.joined_at,
+    }))
+
+    store.setMembers(members)
+    store.setLoading(false)
+    return members
+  }, [supabase, store])
+
+  const updateSettings = useCallback(async (settings: Partial<TenantSettings>) => {
+    if (!store.tenant) throw new Error('No tenant loaded')
+
+    const mergedSettings = { ...store.tenant.settings, ...settings }
+    if (settings.branding) {
+      mergedSettings.branding = { ...store.tenant.settings.branding, ...settings.branding }
+    }
+
+    const { data, error } = await supabase
+      .from('tenants')
+      .update({ settings: mergedSettings, updated_at: new Date().toISOString() })
+      .eq('id', store.tenant.id)
+      .select()
+      .single()
+
+    if (error) throw error
+
+    store.setTenant({
+      ...store.tenant,
+      settings: mergedSettings,
+      updatedAt: data.updated_at,
+    })
+
+    return data
+  }, [supabase, store])
+
+  return {
+    tenant: store.tenant,
+    members: store.members,
+    currentRole: store.currentRole,
+    loading: store.loading,
+    fetchTenant,
+    fetchMembers,
+    updateSettings,
+  }
+}

package/src/shell/hooks/useTenantPlugins.ts

@@ -0,0 +1,103 @@
+import { useEffect } from 'react'
+import { getSupabaseClientOptional } from '../lib/supabase'
+import { useOrganizationStore } from '../stores/organization.store'
+import { usePluginStore } from '../stores/plugin.store'
+
+type TenantActivePluginRow = {
+  plugin_id: string
+  name?: string
+  version?: string
+  scope?: string
+  manifest?: Record<string, unknown>
+  config?: Record<string, unknown>
+  enabled_at?: string
+}
+
+export function useTenantPlugins(options?: { enabled?: boolean }) {
+  const enabled = options?.enabled === true
+  const currentOrg = useOrganizationStore((state) => state.currentOrg)
+  const tenantId = usePluginStore((state) => state.tenantId)
+  const tenantPlugins = usePluginStore((state) => state.tenantPlugins)
+  const activePlugins = usePluginStore((state) => state.activePlugins)
+  const loading = usePluginStore((state) => state.loading)
+  const error = usePluginStore((state) => state.error)
+  const setTenantPlugins = usePluginStore((state) => state.setTenantPlugins)
+  const setLoading = usePluginStore((state) => state.setLoading)
+  const setError = usePluginStore((state) => state.setError)
+  const reset = usePluginStore((state) => state.reset)
+
+  useEffect(() => {
+    if (!enabled) {
+      reset()
+      return
+    }
+
+    if (!currentOrg?.id) {
+      reset()
+      return
+    }
+    const orgId = currentOrg.id
+
+    const supabase = getSupabaseClientOptional()
+    if (!supabase) {
+      reset()
+      return
+    }
+    const supabaseClient = supabase
+
+    let cancelled = false
+
+    async function load() {
+      setLoading(true)
+      setError(null)
+
+      try {
+        const { data, error } = await supabaseClient.rpc('get_tenant_active_plugins', {
+          p_tenant_id: orgId,
+        })
+
+        if (error) {
+          // Plugin system not available in this project — skip silently
+          if (!cancelled) { setLoading(false) }
+          return
+        }
+        if (cancelled) return
+
+        setTenantPlugins(
+          orgId,
+          (data ?? []).map((plugin: TenantActivePluginRow) => ({
+            pluginId: plugin.plugin_id,
+            name: plugin.name,
+            version: plugin.version,
+            scope: plugin.scope,
+            manifest: plugin.manifest,
+            config: plugin.config ?? {},
+            enabledAt: plugin.enabled_at,
+          })),
+        )
+      } catch (error: any) {
+        if (!cancelled) {
+          setError(error?.message ?? 'Failed to load tenant plugins')
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false)
+        }
+      }
+    }
+
+    void load()
+
+    return () => {
+      cancelled = true
+    }
+  }, [currentOrg?.id, enabled, reset, setError, setLoading, setTenantPlugins])
+
+  return {
+    tenantId,
+    tenantPlugins,
+    activePlugins,
+    loading,
+    error,
+  }
+}

package/src/shell/hooks/useTranslation.ts

@@ -0,0 +1,10 @@
+// Compat wrapper → @fayz-ai/core's unified translator. The shell calls
+// `const { t } = useTranslation()`, while @fayz-ai/core returns `t` directly — this
+// keeps the `{ t, locale }` shape so shell components resolve from the SAME
+// registry the native plugins use (registered by createSaasApp).
+import { useTranslation as coreUseTranslation, getCurrentLocale } from '@fayz-ai/core'
+
+export function useTranslation() {
+  const t = coreUseTranslation()
+  return { t, locale: getCurrentLocale() }
+}