@actuate-media/cms-admin 0.68.0 → 0.69.0

package/src/hooks/useIdleLogout.ts

@@ -1,13 +1,31 @@
 'use client'
 
-import { useEffect, useRef } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 
 /** How often the idle checker wakes up to compare against the deadline. */
 const CHECK_INTERVAL_MS = 30_000
 
+export interface UseIdleLogoutOptions {
+  enabled: boolean
+  timeoutMs: number
+  onIdle: () => void
+  /**
+   * How long before the idle deadline to fire `onWarn` (so the UI can show a
+   * "you're about to be signed out" prompt). Ignored unless `onWarn` is set
+   * or when it doesn't fit inside `timeoutMs`.
+   */
+  warningMs?: number
+  /** Fired once when the session enters the warning window. */
+  onWarn?: () => void
+  /** Fired when activity resumes after `onWarn` (dismiss the prompt). */
+  onWarnCancelled?: () => void
+}
+
 /**
  * Signs the user out after `timeoutMs` of no user activity, when enabled by
- * the Settings → Security "Idle auto-logout" policy.
+ * the Settings → Security "Idle auto-logout" policy. Optionally fires a
+ * warning `warningMs` before the deadline so the UI can offer a
+ * "Stay signed in" action (the returned `stayActive` resets the clock).
  *
  * Deliberately lightweight: activity events only stamp a ref (no state, no
  * re-renders), and a single coarse interval compares the last-activity stamp
@@ -17,31 +35,53 @@ const CHECK_INTERVAL_MS = 30_000
  *
  * All listeners and the interval are torn down on unmount or when disabled.
  */
-export function useIdleLogout(options: {
-  enabled: boolean
-  timeoutMs: number
-  onIdle: () => void
-}): void {
-  const { enabled, timeoutMs } = options
-  // Keep the latest callback without re-subscribing listeners on every render.
+export function useIdleLogout(options: UseIdleLogoutOptions): { stayActive: () => void } {
+  const { enabled, timeoutMs, warningMs } = options
+  // Keep the latest callbacks without re-subscribing listeners on every render.
   const onIdleRef = useRef(options.onIdle)
   onIdleRef.current = options.onIdle
+  const onWarnRef = useRef(options.onWarn)
+  onWarnRef.current = options.onWarn
+  const onWarnCancelledRef = useRef(options.onWarnCancelled)
+  onWarnCancelledRef.current = options.onWarnCancelled
+
+  // The effect re-assigns this so `stayActive` always resets the live timer.
+  const resetRef = useRef<() => void>(() => undefined)
 
   useEffect(() => {
-    if (!enabled || timeoutMs <= 0 || typeof window === 'undefined') return
+    if (!enabled || timeoutMs <= 0 || typeof window === 'undefined') {
+      resetRef.current = () => undefined
+      return
+    }
 
     let lastActivity = Date.now()
     let fired = false
+    let warned = false
+
+    // Only meaningful when a warn callback exists and the window fits.
+    const effectiveWarningMs =
+      onWarnRef.current && warningMs && warningMs > 0 && warningMs < timeoutMs ? warningMs : 0
 
     const markActivity = () => {
       lastActivity = Date.now()
+      if (warned && !fired) {
+        warned = false
+        onWarnCancelledRef.current?.()
+      }
     }
+    resetRef.current = markActivity
 
     const checkIdle = () => {
       if (fired) return
-      if (Date.now() - lastActivity >= timeoutMs) {
+      const idleFor = Date.now() - lastActivity
+      if (idleFor >= timeoutMs) {
         fired = true
         onIdleRef.current()
+        return
+      }
+      if (effectiveWarningMs > 0 && !warned && idleFor >= timeoutMs - effectiveWarningMs) {
+        warned = true
+        onWarnRef.current?.()
       }
     }
 
@@ -64,14 +104,26 @@ export function useIdleLogout(options: {
     }
     document.addEventListener('visibilitychange', onVisibility)
 
-    const interval = window.setInterval(checkIdle, Math.min(CHECK_INTERVAL_MS, timeoutMs))
+    // Tick often enough to hit the warning window, not just the deadline.
+    const tick =
+      effectiveWarningMs > 0
+        ? Math.min(CHECK_INTERVAL_MS, timeoutMs, effectiveWarningMs)
+        : Math.min(CHECK_INTERVAL_MS, timeoutMs)
+    const interval = window.setInterval(checkIdle, tick)
 
     return () => {
+      resetRef.current = () => undefined
       for (const event of activityEvents) {
         window.removeEventListener(event, markActivity)
       }
       document.removeEventListener('visibilitychange', onVisibility)
       window.clearInterval(interval)
     }
-  }, [enabled, timeoutMs])
+  }, [enabled, timeoutMs, warningMs])
+
+  const stayActive = useCallback(() => {
+    resetRef.current()
+  }, [])
+
+  return { stayActive }
 }

package/src/router/index.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useCallback, useEffect, useRef } from 'react'
+import { useState, useCallback, useEffect, useMemo, useRef } from 'react'
 
 interface RouteParams {
   [key: string]: string
@@ -14,6 +14,15 @@ function stripBase(pathname: string, basePath: string): string {
   return '/'
 }
 
+/**
+ * Parse the query string out of an admin path (`/pages/new?parent=abc`) or a
+ * raw search string (`?parent=abc`) into `URLSearchParams`. Pure helper for
+ * view components that only receive `currentPath` / `onNavigate` props.
+ */
+export function parseRouteQuery(path: string): URLSearchParams {
+  return new URLSearchParams(path.split('#')[0]!.split('?')[1] ?? '')
+}
+
 export function useAdminRouter(basePath = '/admin', serverPath = '/') {
   const [currentPath, setCurrentPath] = useState(serverPath)
   const baseRef = useRef(basePath)
@@ -21,7 +30,10 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
 
   useEffect(() => {
     if (typeof window !== 'undefined') {
-      const browserPath = stripBase(window.location.pathname, basePath)
+      // Include the query string so state-bearing URLs (`/pages/new?parent=x`,
+      // `/settings?tab=users`) survive hard reloads. matchRoute strips the
+      // query before matching, so `/?foo=1` still resolves to `/`.
+      const browserPath = stripBase(window.location.pathname, basePath) + window.location.search
       if (browserPath !== currentPath) {
         setCurrentPath(browserPath)
       }
@@ -30,7 +42,9 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
 
   useEffect(() => {
     function onPopState() {
-      setCurrentPath(stripBase(window.location.pathname, baseRef.current))
+      // Query string included for the same reason as the mount sync above —
+      // back/forward must restore deep-link state, not just the pathname.
+      setCurrentPath(stripBase(window.location.pathname, baseRef.current) + window.location.search)
     }
     window.addEventListener('popstate', onPopState)
     return () => window.removeEventListener('popstate', onPopState)
@@ -92,5 +106,12 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
     [currentPath],
   )
 
-  return { currentPath, navigate, matchRoute, buildHref }
+  // Raw query string of the current route (`?tab=users`), or '' when absent.
+  // Views wanting parsed params can pass it (or currentPath) to parseRouteQuery.
+  const search = useMemo(() => {
+    const queryIndex = currentPath.indexOf('?')
+    return queryIndex === -1 ? '' : currentPath.slice(queryIndex).split('#')[0]!
+  }, [currentPath])
+
+  return { currentPath, search, navigate, matchRoute, buildHref }
 }

package/src/views/MediaBrowser.tsx

@@ -24,8 +24,9 @@ import {
   FolderInput,
   GripVertical,
 } from 'lucide-react'
-import { useState, useMemo, useRef, useCallback } from 'react'
+import { useState, useMemo, useRef, useCallback, useEffect } from 'react'
 import { toast } from 'sonner'
+import { parseRouteQuery } from '../router/index.js'
 import { sortByRelevance, type SortConfig, toggleSort } from '../lib/search.js'
 import { useApiData } from '../lib/useApiData.js'
 import { cmsApi } from '../lib/api.js'
@@ -97,6 +98,9 @@ type MediaSortKey = 'name' | 'type' | 'size' | 'date'
 
 export interface MediaBrowserProps {
   onNavigate?: (path: string) => void
+  /** Router path including the query string. `?selected=<mediaId>` (written by
+   * the command palette) opens that item's detail panel once the list loads. */
+  currentPath?: string
 }
 
 function buildMediaApiUrl(folderSel: FolderSelection): string {
@@ -109,7 +113,7 @@ function buildMediaApiUrl(folderSel: FolderSelection): string {
   return `${base}&folderId=${folderSel.folderId}`
 }
 
-export function MediaBrowser({ onNavigate }: MediaBrowserProps) {
+export function MediaBrowser({ onNavigate, currentPath }: MediaBrowserProps) {
   const [folderSel, setFolderSel] = useState<FolderSelection>({ type: 'smart', smart: 'all' })
   const [sidebarOpen, setSidebarOpen] = useState(true)
 
@@ -144,7 +148,7 @@ export function MediaBrowser({ onNavigate }: MediaBrowserProps) {
   const [uploading, setUploading] = useState(false)
   const fileInputRef = useRef<HTMLInputElement>(null)
 
-  const mediaItems = data?.data ?? data?.items ?? []
+  const mediaItems = useMemo(() => data?.data ?? data?.items ?? [], [data])
 
   const filteredAndSorted = useMemo(() => {
     let results = mediaItems.filter((item) => {
@@ -185,7 +189,7 @@ export function MediaBrowser({ onNavigate }: MediaBrowserProps) {
     return { total: mediaItems.length, images, videos, documents, bytes }
   }, [mediaItems])
 
-  const openDetail = (item: MediaItem) => {
+  const openDetail = useCallback((item: MediaItem) => {
     setActiveItem(item)
     setEditAlt(item.altTag ?? '')
     setEditTitle(item.title ?? '')
@@ -193,7 +197,26 @@ export function MediaBrowser({ onNavigate }: MediaBrowserProps) {
     setEditCaption(item.caption ?? '')
     setEditDescription(item.description ?? '')
     setEditFocusKeyword(item.focusKeyword ?? '')
-  }
+  }, [])
+
+  // Deep link from the command palette (`/media?selected=<id>`): open the
+  // item's detail panel once the library loads. Each query value is handled
+  // once, so closing the panel doesn't get overridden on refetch; unknown
+  // ids are ignored.
+  const selectedMediaId = useMemo(() => {
+    const source = currentPath ?? (typeof window !== 'undefined' ? window.location.search : '')
+    return parseRouteQuery(source).get('selected')
+  }, [currentPath])
+  const handledSelectedRef = useRef<string | null>(null)
+  useEffect(() => {
+    if (!selectedMediaId || loading) return
+    if (handledSelectedRef.current === selectedMediaId) return
+    const item = mediaItems.find((m) => String(m.id) === selectedMediaId)
+    if (!item) return
+    handledSelectedRef.current = selectedMediaId
+    setActiveTab('library')
+    openDetail(item)
+  }, [selectedMediaId, loading, mediaItems, openDetail])
 
   // Count of items missing alt OR title — drives the SEO Audit tab badge.
   const auditAttentionCount = useMemo(

package/src/views/SEO.tsx

@@ -18,6 +18,7 @@ import {
 } from 'lucide-react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { toast } from 'sonner'
+import { parseRouteQuery } from '../router/index.js'
 import { ErrorBoundary } from '../components/ErrorBoundary.js'
 import { fetchSeoOverview, runSeoAudit } from '../lib/seo-service.js'
 import { fetchPlanInfo, type PlanInfo } from '../lib/plan.js'
@@ -62,7 +63,7 @@ function readUrlState(): UrlState {
   if (typeof window === 'undefined') {
     return { tab: null, entityType: null, entityId: null, issueId: null }
   }
-  const params = new URLSearchParams(window.location.search)
+  const params = parseRouteQuery(window.location.search)
   return {
     tab: params.get('tab'),
     entityType: params.get('entityType'),

package/src/views/Settings.tsx

@@ -13,6 +13,7 @@ import {
 } from 'lucide-react'
 import { useState, useEffect, useCallback, useMemo } from 'react'
 import { toast } from 'sonner'
+import { parseRouteQuery } from '../router/index.js'
 import { useApiData } from '../lib/useApiData.js'
 import { cmsApi } from '../lib/api.js'
 import { RelationshipField } from '../fields/RelationshipField.js'
@@ -35,6 +36,9 @@ export interface SettingsProps {
   /** Initial tab when arriving without a `?tab=` query param (e.g. via the
    * legacy `/users` or `/api-keys` routes). */
   initialTab?: string
+  /** Router path including the query string (e.g. `/users?selected=<id>`).
+   * Forwarded to embedded tab views so their deep links keep working. */
+  currentPath?: string
 }
 
 /**
@@ -48,7 +52,7 @@ const GLOBAL_SAVE_TABS = new Set(['layout'])
 
 function readSettingsTabFromUrl(): string | null {
   if (typeof window === 'undefined') return null
-  return new URLSearchParams(window.location.search).get('tab')
+  return parseRouteQuery(window.location.search).get('tab')
 }
 
 export function Settings({
@@ -56,6 +60,7 @@ export function Settings({
   onNavigate,
   session,
   initialTab = 'general',
+  currentPath,
 }: SettingsProps = {}) {
   const { data, loading, error, refetch } = useApiData<any>('/globals/settings')
 
@@ -329,7 +334,7 @@ export function Settings({
         </Tabs.Content>
 
         <Tabs.Content value="users">
-          <UsersView onNavigate={onNavigate} embedded />
+          <UsersView onNavigate={onNavigate} embedded currentPath={currentPath} />
         </Tabs.Content>
 
         <Tabs.Content value="api-keys">

package/src/views/Users.tsx

@@ -22,8 +22,9 @@ import {
   Check,
   SlidersHorizontal,
 } from 'lucide-react'
-import { useState, useMemo, useCallback, type FormEvent } from 'react'
+import { useState, useMemo, useCallback, useEffect, useRef, type FormEvent } from 'react'
 import { toast } from 'sonner'
+import { parseRouteQuery } from '../router/index.js'
 import { useApiData } from '../lib/useApiData.js'
 import { cmsApi } from '../lib/api.js'
 import { Button } from '../components/ui/Button.js'
@@ -675,9 +676,12 @@ const ROLE_PILLS: Array<'All' | 'Owner' | 'Admin' | 'Editor' | 'Viewer'> = [
 export interface UsersProps {
   onNavigate?: (path: string) => void
   embedded?: boolean
+  /** Router path including the query string. `?selected=<userId>` (written by
+   * the command palette) opens that member's detail drawer once the list loads. */
+  currentPath?: string
 }
 
-export function Users({ embedded = false }: UsersProps = {}) {
+export function Users({ embedded = false, currentPath }: UsersProps = {}) {
   const members = useApiData<ApiMember[]>('/users?pageSize=200')
   const invites = useApiData<ApiInvite[]>('/invites')
   const stats = useApiData<ApiStats>('/users/stats')
@@ -702,6 +706,23 @@ export function Users({ embedded = false }: UsersProps = {}) {
     review.refetch()
   }, [members, invites, stats, review])
 
+  // Deep link from the command palette (`/users?selected=<id>`): open the
+  // member's detail drawer once the list loads. Each query value is handled
+  // once, so closing the drawer isn't overridden on refetch; ids that don't
+  // match a loaded member are ignored.
+  const selectedUserId = useMemo(() => {
+    const source = currentPath ?? (typeof window !== 'undefined' ? window.location.search : '')
+    return parseRouteQuery(source).get('selected')
+  }, [currentPath])
+  const handledSelectedRef = useRef<string | null>(null)
+  useEffect(() => {
+    if (!selectedUserId || members.loading) return
+    if (handledSelectedRef.current === selectedUserId) return
+    if (!(members.data ?? []).some((m) => m.id === selectedUserId)) return
+    handledSelectedRef.current = selectedUserId
+    setDetailUserId(selectedUserId)
+  }, [selectedUserId, members.loading, members.data])
+
   const currentUserRole = useMemo(
     () => (members.data ?? []).find((m) => m.isCurrentUser)?.roleName ?? null,
     [members.data],

package/src/views/settings/SecurityTab.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect } from 'react'
 import { Loader2, ShieldAlert } from 'lucide-react'
+import { parseRouteQuery } from '../../router/index.js'
 import {
   ConfirmDangerousSettingDialog,
   SettingsSaveBar,
@@ -56,7 +57,7 @@ export function SecurityTab({
   // Deep-link support: /settings?tab=security&section=sessions|ip-allowlist|audit
   useEffect(() => {
     if (loading || typeof window === 'undefined') return
-    const section = new URLSearchParams(window.location.search).get('section')
+    const section = parseRouteQuery(window.location.search).get('section')
     if (!section) return
     const el = document.getElementById(`security-${section}`)
     el?.scrollIntoView({ behavior: 'smooth', block: 'start' })