feat: add useTenantFeatures hook and feature visibility system (#1394)

* feat: add useTenantFeatures hook and feature visibility system

- Create use-tenant-features.ts hook returning isFeatureEnabled, enabledFeatures, defaultFeature
- Reads tenantConfig from TenantContext, falls back to DEFAULT_UI_CONFIG
- Re-export ALL_FEATURES from tenant-ui-config for consumers
- Add tenantConfig field to TenantContextValue interface in tenant-context.tsx
- Populate tenantConfig with DEFAULT_UI_CONFIG in TenantProvider value
- Add unit tests covering defaults, filtering, isFeatureEnabled, and fallback paths

* refactor: memoize useTenantFeatures and validate defaultFeature against enabled list

- Wrap computation in useMemo to avoid re-creating Set and callback on every render
- Fall back to first enabled feature when configured defaultFeature is not in enabled list
- Add test covering defaultFeature fallback when configured default is disabled

* fix: return empty string for defaultFeature when enabled list is empty

Avoids inconsistency where defaultFeature would resolve to 'dashboard'
but isFeatureEnabled('dashboard') returns false. When no features are
enabled, defaultFeature is now an empty string.

* fix: treat empty enabled list as default (all features) in useTenantFeatures

An empty features.enabled array is treated the same as an absent config —
fall back to all features. This avoids the inconsistency where defaultFeature
could resolve to a feature not present in the enabled set.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/src/contexts/tenant-context.tsx

@@ -1,6 +1,7 @@
 import { createContext, useContext, useState, useCallback, type ReactNode } from 'react'
 import { useQueryClient } from '@tanstack/react-query'
 import { useAuth } from '@/contexts/auth-context'
+import { DEFAULT_UI_CONFIG, type TenantUIConfig } from '@/lib/tenant-ui-config'
 
 export interface Tenant {
   id: string
@@ -14,6 +15,7 @@ export interface TenantContextValue {
   isPlatformAdmin: boolean
   switchTenant: (tenant: Tenant) => void
   clearTenant: () => void
+  tenantConfig?: TenantUIConfig
 }
 
 const TenantContext = createContext<TenantContextValue | null>(null)
@@ -59,6 +61,7 @@ export function TenantProvider({ children }: { children: ReactNode }) {
     isPlatformAdmin,
     switchTenant,
     clearTenant,
+    tenantConfig: DEFAULT_UI_CONFIG,
   }
 
   return <TenantContext.Provider value={value}>{children}</TenantContext.Provider>

frontend/src/hooks/__tests__/use-tenant-features.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { useTenantFeatures, ALL_FEATURES } from '../use-tenant-features'
+import type { TenantContextValue } from '@/contexts/tenant-context'
+import { DEFAULT_UI_CONFIG } from '@/lib/tenant-ui-config'
+
+vi.mock('@/contexts/tenant-context', () => ({
+  useTenantContext: vi.fn(),
+}))
+
+import { useTenantContext } from '@/contexts/tenant-context'
+
+function makeContext(overrides: Partial<TenantContextValue> = {}): TenantContextValue {
+  return {
+    currentTenant: null,
+    tenantSlug: null,
+    isPlatformAdmin: false,
+    switchTenant: vi.fn(),
+    clearTenant: vi.fn(),
+    ...overrides,
+  }
+}
+
+describe('useTenantFeatures', () => {
+  it('returns all features enabled when no tenantConfig is set', () => {
+    vi.mocked(useTenantContext).mockReturnValue(makeContext())
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.enabledFeatures).toEqual([...ALL_FEATURES])
+    expect(result.current.defaultFeature).toBe('dashboard')
+  })
+
+  it('returns all features enabled when using DEFAULT_UI_CONFIG', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({ tenantConfig: DEFAULT_UI_CONFIG }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.enabledFeatures).toEqual([...ALL_FEATURES])
+    ALL_FEATURES.forEach((f) => {
+      expect(result.current.isFeatureEnabled(f)).toBe(true)
+    })
+  })
+
+  it('correctly filters disabled features when config limits enabled list', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({
+        tenantConfig: {
+          features: {
+            enabled: ['dashboard', 'accounts', 'payments'],
+            defaultFeature: 'dashboard',
+          },
+        },
+      }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.enabledFeatures).toEqual(['dashboard', 'accounts', 'payments'])
+    expect(result.current.isFeatureEnabled('dashboard')).toBe(true)
+    expect(result.current.isFeatureEnabled('accounts')).toBe(true)
+    expect(result.current.isFeatureEnabled('payments')).toBe(true)
+    expect(result.current.isFeatureEnabled('ledger')).toBe(false)
+    expect(result.current.isFeatureEnabled('tenants')).toBe(false)
+  })
+
+  it('isFeatureEnabled returns false for unknown feature names', () => {
+    vi.mocked(useTenantContext).mockReturnValue(makeContext({ tenantConfig: DEFAULT_UI_CONFIG }))
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.isFeatureEnabled('nonexistent-feature')).toBe(false)
+  })
+
+  it('uses custom defaultFeature from config', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({
+        tenantConfig: {
+          features: {
+            enabled: ['accounts', 'payments'],
+            defaultFeature: 'accounts',
+          },
+        },
+      }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.defaultFeature).toBe('accounts')
+  })
+
+  it('falls back to dashboard as defaultFeature when config has no defaultFeature', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({
+        tenantConfig: {
+          features: {
+            enabled: ['dashboard', 'accounts'],
+          },
+        },
+      }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.defaultFeature).toBe('dashboard')
+  })
+
+  it('falls back gracefully when tenantConfig has no features key', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({
+        tenantConfig: {},
+      }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    expect(result.current.enabledFeatures).toEqual([...ALL_FEATURES])
+    expect(result.current.defaultFeature).toBe('dashboard')
+    expect(result.current.isFeatureEnabled('dashboard')).toBe(true)
+  })
+
+  it('falls back to first enabled feature when configured default is not in enabled list', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({
+        tenantConfig: {
+          features: {
+            enabled: ['accounts', 'payments'],
+            defaultFeature: 'dashboard', // dashboard is NOT in the enabled list
+          },
+        },
+      }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    // Should fall back to first enabled feature, not the disabled default
+    expect(result.current.defaultFeature).toBe('accounts')
+  })
+
+  it('falls back to all features when enabled list is empty', () => {
+    vi.mocked(useTenantContext).mockReturnValue(
+      makeContext({
+        tenantConfig: {
+          features: {
+            enabled: [],
+          },
+        },
+      }),
+    )
+
+    const { result } = renderHook(() => useTenantFeatures())
+
+    // Empty enabled list is treated as "use defaults" — all features enabled
+    expect(result.current.enabledFeatures).toEqual([...ALL_FEATURES])
+    expect(result.current.isFeatureEnabled('dashboard')).toBe(true)
+    expect(result.current.defaultFeature).toBe('dashboard')
+  })
+})

frontend/src/hooks/use-tenant-features.ts

@@ -0,0 +1,41 @@
+import { useMemo } from 'react'
+import { useTenantContext } from '@/contexts/tenant-context'
+import {
+  ALL_FEATURES,
+  DEFAULT_UI_CONFIG,
+  type FeatureId,
+} from '@/lib/tenant-ui-config'
+
+export { ALL_FEATURES }
+
+export interface TenantFeaturesResult {
+  isFeatureEnabled: (feature: string) => boolean
+  enabledFeatures: readonly FeatureId[]
+  defaultFeature: string
+}
+
+export function useTenantFeatures(): TenantFeaturesResult {
+  const { tenantConfig } = useTenantContext()
+
+  return useMemo(() => {
+    const config = tenantConfig ?? DEFAULT_UI_CONFIG
+
+    // Treat an empty enabled list the same as an absent one — fall back to all features
+    const configuredEnabled = config.features?.enabled ?? [...ALL_FEATURES]
+    const enabledFeatures = configuredEnabled.length > 0 ? configuredEnabled : [...ALL_FEATURES]
+    const enabledSet = new Set<string>(enabledFeatures)
+
+    // Fall back to the first enabled feature if the configured default is not in the enabled list
+    const configuredDefault =
+      config.features?.defaultFeature ?? DEFAULT_UI_CONFIG.features!.defaultFeature!
+    const defaultFeature = enabledSet.has(configuredDefault)
+      ? configuredDefault
+      : enabledFeatures[0]
+
+    return {
+      isFeatureEnabled: (feature: string) => enabledSet.has(feature),
+      enabledFeatures,
+      defaultFeature,
+    }
+  }, [tenantConfig])
+}