refactor(admin): refactor admin roles and users management

src/app/(modules)/roles/components/RoleColumns.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { ColumnDef } from '@tanstack/react-table';
+import { Edit, RotateCcw } from 'lucide-react';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import type { Role } from '@/types';
+
+interface UseRoleColumnsParams {
+  onEdit: (role: Role) => void;
+  onToggleStatus: (role: Role) => void;
+  isStatusPending: boolean;
+}
+
+export function useRoleColumns({
+  onEdit,
+  onToggleStatus,
+  isStatusPending,
+}: UseRoleColumnsParams): ColumnDef<Role>[] {
+  return useMemo(
+    () => [
+      {
+        accessorKey: 'name',
+        header: 'Name',
+        cell: ({ row }) => <span className="font-medium">{row.original.name}</span>,
+      },
+      {
+        accessorKey: 'display_name',
+        header: 'Display Name',
+      },
+      {
+        accessorKey: 'description',
+        header: 'Description',
+        cell: ({ row }) => (
+          <span className="block max-w-sm truncate text-muted-foreground">
+            {row.original.description || '-'}
+          </span>
+        ),
+      },
+      {
+        accessorKey: 'user_count',
+        header: 'Users',
+        cell: ({ row }) => row.original.user_count ?? 0,
+      },
+      {
+        accessorKey: 'effective_status',
+        header: 'Status',
+        cell: ({ row }) => (
+          <Badge variant={row.original.effective_status ? 'default' : 'secondary'}>
+            {row.original.effective_status ? 'Active' : 'Inactive'}
+          </Badge>
+        ),
+      },
+      {
+        id: 'actions',
+        header: () => <div className="text-right">Actions</div>,
+        cell: ({ row }) => {
+          const role = row.original;
+          return (
+            <div className="flex justify-end gap-2">
+              <Button variant="outline" size="sm" onClick={() => onEdit(role)}>
+                <Edit className="size-4" />
+              </Button>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={isStatusPending}
+                onClick={() => onToggleStatus(role)}
+              >
+                <RotateCcw className="mr-2 size-4" />
+                {role.effective_status ? 'Deactivate' : 'Activate'}
+              </Button>
+            </div>
+          );
+        },
+      },
+    ],
+    [isStatusPending, onEdit, onToggleStatus],
+  );
+}

src/app/(modules)/roles/components/RoleFilters.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { Input } from '@/components/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+
+import type { StatusFilter } from '../hooks/useRoleFilters';
+
+interface RoleFiltersProps {
+  searchTerm: string;
+  statusFilter: StatusFilter;
+  onSearchChange: (value: string) => void;
+  onStatusChange: (value: StatusFilter) => void;
+}
+
+export function RoleFilters({
+  searchTerm,
+  statusFilter,
+  onSearchChange,
+  onStatusChange,
+}: RoleFiltersProps) {
+  return (
+    <div className="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+      <Input
+        value={searchTerm}
+        onChange={(event) => onSearchChange(event.target.value)}
+        placeholder="Search roles"
+        className="md:max-w-sm"
+      />
+      <Select value={statusFilter} onValueChange={(value) => onStatusChange(value as StatusFilter)}>
+        <SelectTrigger className="md:w-44">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All status</SelectItem>
+          <SelectItem value="active">Active</SelectItem>
+          <SelectItem value="inactive">Inactive</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}

src/app/(modules)/roles/components/RoleSheet.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+import type { UseFormRegister } from 'react-hook-form';
+import { Loader2 } from 'lucide-react';
+
+import { PermissionTree } from '@/components/permission-tree';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from '@/components/ui/sheet';
+import type { PermissionTreeItem } from '@/types';
+
+import type { RoleFormValues } from '../hooks/useRoleForm';
+
+interface RoleSheetProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  roleId?: number;
+  register: UseFormRegister<RoleFormValues>;
+  onSubmit: ComponentProps<'form'>['onSubmit'];
+  permissionTree: PermissionTreeItem[];
+  permissionIds: number[];
+  onPermissionIdsChange: (ids: number[]) => void;
+  isPermissionsLoading: boolean;
+  isSaving: boolean;
+}
+
+export function RoleSheet({
+  open,
+  onOpenChange,
+  roleId,
+  register,
+  onSubmit,
+  permissionTree,
+  permissionIds,
+  onPermissionIdsChange,
+  isPermissionsLoading,
+  isSaving,
+}: RoleSheetProps) {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent className="w-full overflow-y-auto sm:max-w-2xl">
+        <SheetHeader>
+          <SheetTitle>{roleId ? 'Edit Role' : 'Create Role'}</SheetTitle>
+          <SheetDescription>
+            Assign the role details and permission access for this organization.
+          </SheetDescription>
+        </SheetHeader>
+        <form onSubmit={onSubmit} className="flex flex-1 flex-col gap-5 px-4">
+          <div className="grid gap-4 md:grid-cols-2">
+            <div className="space-y-2">
+              <Label htmlFor="role-name">Role Name</Label>
+              <Input
+                id="role-name"
+                placeholder="Enter role name"
+                {...register('name', { required: true })}
+                required
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="role-display-name">Display Name</Label>
+              <Input
+                id="role-display-name"
+                placeholder="Enter display name"
+                {...register('display_name', { required: true })}
+                required
+              />
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="role-description">Description</Label>
+            <textarea
+              id="role-description"
+              placeholder="Describe this role"
+              {...register('description')}
+              className="min-h-24 w-full rounded-md border border-input bg-background px-3 py-2 text-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            />
+          </div>
+
+          <div className="space-y-3">
+            <div className="flex items-center justify-between gap-3">
+              <Label>Permissions</Label>
+              <span className="text-xs text-muted-foreground">{permissionIds.length} selected</span>
+            </div>
+            {isPermissionsLoading ? (
+              <div className="rounded-md border p-6 text-sm text-muted-foreground">
+                Loading permissions...
+              </div>
+            ) : (
+              <PermissionTree
+                items={permissionTree}
+                selectedIds={permissionIds}
+                onChange={onPermissionIdsChange}
+              />
+            )}
+          </div>
+
+          <SheetFooter className="px-0">
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => onOpenChange(false)}
+              disabled={isSaving}
+            >
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSaving}>
+              {isSaving ? <Loader2 className="mr-2 size-4 animate-spin" /> : null}
+              {roleId ? 'Update Role' : 'Create Role'}
+            </Button>
+          </SheetFooter>
+        </form>
+      </SheetContent>
+    </Sheet>
+  );
+}

src/app/(modules)/roles/components/RoleTable.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import type { ColumnDef } from '@tanstack/react-table';
+import type { ReactNode } from 'react';
+
+import { DataTable } from '@/components/data-table';
+import type { Role } from '@/types';
+
+interface RoleTableProps {
+  columns: ColumnDef<Role>[];
+  roles: Role[];
+  isLoading: boolean;
+  toolbar: ReactNode;
+  skip: number;
+  limit: number;
+  total: number;
+  onPageChange: (skip: number) => void;
+}
+
+export function RoleTable({
+  columns,
+  roles,
+  isLoading,
+  toolbar,
+  skip,
+  limit,
+  total,
+  onPageChange,
+}: RoleTableProps) {
+  return (
+    <DataTable
+      title="Roles"
+      columns={columns}
+      data={roles}
+      isLoading={isLoading}
+      toolbar={toolbar}
+      emptyTitle="No roles found."
+      pagination={{
+        skip,
+        limit,
+        totalItems: total,
+        onPageChange,
+        onLimitChange: () => undefined,
+      }}
+    />
+  );
+}

src/app/(modules)/roles/hooks/useRoleFilters.ts

@@ -0,0 +1,44 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export type StatusFilter = 'all' | 'active' | 'inactive';
+
+const SEARCH_DEBOUNCE_MS = 400;
+
+export function useRoleFilters() {
+  const [skip, setSkip] = useState(0);
+  const [limit] = useState(10);
+  const [searchTerm, setSearchTermValue] = useState('');
+  const [debouncedSearchTerm, setDebouncedSearchTerm] = useState('');
+  const [statusFilter, setStatusFilterValue] = useState<StatusFilter>('all');
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => {
+      setDebouncedSearchTerm(searchTerm.trim());
+    }, SEARCH_DEBOUNCE_MS);
+
+    return () => window.clearTimeout(timer);
+  }, [searchTerm]);
+
+  const setSearchTerm = (value: string) => {
+    setSearchTermValue(value);
+    setSkip(0);
+  };
+
+  const setStatusFilter = (value: StatusFilter) => {
+    setStatusFilterValue(value);
+    setSkip(0);
+  };
+
+  return {
+    skip,
+    setSkip,
+    limit,
+    searchTerm,
+    debouncedSearchTerm,
+    setSearchTerm,
+    statusFilter,
+    setStatusFilter,
+  };
+}

src/app/(modules)/roles/hooks/useRoleForm.ts

@@ -0,0 +1,120 @@
+'use client';
+
+import {
+  collectDefaultPermissionIds,
+  collectPermissionIdsByKeys,
+} from '@/components/permission-tree';
+import { roleService } from '@/services/api';
+import type { PermissionTreeItem, Role } from '@/types';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useCallback } from 'react';
+import { useForm, useWatch } from 'react-hook-form';
+import { toast } from 'sonner';
+
+import { roleKeys } from '../queries/roleKeys';
+
+export interface RoleFormValues {
+  id?: number;
+  name: string;
+  display_name: string;
+  description: string;
+  permission_ids: number[];
+}
+
+const defaultValues: RoleFormValues = {
+  name: '',
+  display_name: '',
+  description: '',
+  permission_ids: [],
+};
+
+export function useRoleForm({
+  organizationId,
+  permissionTree,
+  onSaved,
+}: {
+  organizationId: number | null;
+  permissionTree: PermissionTreeItem[];
+  onSaved: () => void;
+}) {
+  const queryClient = useQueryClient();
+  const {
+    control,
+    register,
+    handleSubmit,
+    reset,
+    setValue,
+    formState: { isSubmitting },
+  } = useForm<RoleFormValues>({
+    defaultValues,
+  });
+
+  const permissionIds = useWatch({ control, name: 'permission_ids' }) || [];
+  const roleId = useWatch({ control, name: 'id' });
+
+  const saveMutation = useMutation({
+    mutationFn: (values: RoleFormValues) =>
+      roleService.saveRole({
+        id: values.id,
+        name: values.name.trim(),
+        display_name: values.display_name.trim(),
+        description: values.description.trim(),
+        organization_id: organizationId,
+        permission_ids: values.permission_ids,
+        is_default: false,
+      }),
+    onSuccess: (_data, values) => {
+      toast.success(values.id ? 'Role updated' : 'Role created');
+      reset(defaultValues);
+      onSaved();
+      queryClient.invalidateQueries({ queryKey: roleKeys.all });
+    },
+    onError: (_error, values) => {
+      toast.error(values.id ? 'Failed to update role' : 'Failed to create role');
+    },
+  });
+
+  const onSubmit = handleSubmit((values) => {
+    if (values.permission_ids.length === 0) {
+      toast.error('Select at least one permission');
+      return;
+    }
+    saveMutation.mutate(values);
+  });
+
+  const openCreate = useCallback(() => {
+    reset({
+      ...defaultValues,
+      permission_ids: collectDefaultPermissionIds(permissionTree),
+    });
+  }, [permissionTree, reset]);
+
+  const openEdit = useCallback(
+    (role: Role) => {
+      reset({
+        id: role.id,
+        name: role.name || '',
+        display_name: role.display_name || '',
+        description: role.description || '',
+        permission_ids: collectPermissionIdsByKeys(permissionTree, role.permissions || []),
+      });
+    },
+    [permissionTree, reset],
+  );
+
+  const setPermissionIds = useCallback(
+    (ids: number[]) => setValue('permission_ids', ids, { shouldDirty: true, shouldValidate: true }),
+    [setValue],
+  );
+
+  return {
+    register,
+    onSubmit,
+    openCreate,
+    openEdit,
+    setPermissionIds,
+    permissionIds,
+    roleId,
+    isSaving: isSubmitting || saveMutation.isPending,
+  };
+}

src/app/(modules)/roles/hooks/useRoleQueries.ts

@@ -0,0 +1,77 @@
+'use client';
+
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import { toast } from 'sonner';
+
+import { mapPermissionTree } from '@/components/permission-tree';
+import { permissionService, roleService } from '@/services/api';
+import type { Role, RoleListParams } from '@/types';
+
+import { roleKeys } from '../queries/roleKeys';
+import type { StatusFilter } from './useRoleFilters';
+
+interface UseRolesQueryParams {
+  skip: number;
+  limit: number;
+  searchTerm: string;
+  statusFilter: StatusFilter;
+}
+
+function buildRoleListParams({
+  skip,
+  limit,
+  searchTerm,
+  statusFilter,
+}: UseRolesQueryParams): RoleListParams {
+  return {
+    skip,
+    limit,
+    search_term: searchTerm || undefined,
+    effective_status: statusFilter === 'all' ? undefined : statusFilter === 'active',
+    sort_by: 'created_at',
+    sort_order: 'desc',
+  };
+}
+
+export function useRolesQuery(params: UseRolesQueryParams) {
+  const { skip, limit, searchTerm, statusFilter } = params;
+  const listParams = useMemo(
+    () => buildRoleListParams({ skip, limit, searchTerm, statusFilter }),
+    [limit, searchTerm, skip, statusFilter],
+  );
+
+  return useQuery({
+    queryKey: roleKeys.list(listParams),
+    queryFn: () => roleService.getRoles(listParams),
+  });
+}
+
+export function usePermissionsTreeQuery() {
+  const permissionsQuery = useQuery({
+    queryKey: ['permissions', 'tree'],
+    queryFn: permissionService.getPermissions,
+  });
+  const permissionTree = useMemo(
+    () => mapPermissionTree(permissionsQuery.data?.tree || []),
+    [permissionsQuery.data?.tree],
+  );
+
+  return {
+    ...permissionsQuery,
+    permissionTree,
+  };
+}
+
+export function useRoleStatusMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (role: Role) => roleService.updateRoleStatus(role.id, !role.effective_status),
+    onSuccess: () => {
+      toast.success('Role status updated');
+      queryClient.invalidateQueries({ queryKey: roleKeys.all });
+    },
+    onError: () => toast.error('Failed to update role status'),
+  });
+}

src/app/(modules)/roles/page.tsx

@@ -1,388 +1,100 @@
 'use client';
 
-import { FormEvent, useEffect, useMemo, useRef, useState } from 'react';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { Edit, Loader2, Plus, RotateCcw, ShieldCheck } from 'lucide-react';
-import { toast } from 'sonner';
-import type { ColumnDef } from '@tanstack/react-table';
+import { useCallback, useState } from 'react';
+import { Plus, ShieldCheck } from 'lucide-react';
 
-import { DataTable } from '@/components/data-table';
 import { PageHeader } from '@/components/page-header';
 import { PoweredBy } from '@/components/powered-by';
-import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
-import { Input } from '@/components/ui/input';
-import { Label } from '@/components/ui/label';
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import {
-  Sheet,
-  SheetContent,
-  SheetDescription,
-  SheetFooter,
-  SheetHeader,
-  SheetTitle,
-} from '@/components/ui/sheet';
-import { cn } from '@/lib/utils';
-import { permissionService, roleService } from '@/services/api';
 import { useAppStore } from '@/store/app.store';
-import type { PermissionTreeItem, PermissionTreeNode, Role } from '@/types';
+import type { Role } from '@/types';
 
-type StatusFilter = 'all' | 'active' | 'inactive';
-
-interface RoleFormState {
-  id?: number;
-  name: string;
-  display_name: string;
-  description: string;
-  permission_ids: number[];
-}
-
-const emptyRoleForm: RoleFormState = {
-  name: '',
-  display_name: '',
-  description: '',
-  permission_ids: [],
-};
-
-function mapPermissionTree(nodes: PermissionTreeNode[]): PermissionTreeItem[] {
-  return nodes.map((node) => ({
-    id: node.id,
-    key: node.slug || node.name,
-    label: node.display_name || node.name,
-    description: node.description,
-    type: node.type,
-    isGrantedByDefault: Boolean(node.is_granted_by_default),
-    children: mapPermissionTree(node.children || []),
-  }));
-}
-
-function collectNodeIds(node: PermissionTreeItem): number[] {
-  return [node.id, ...node.children.flatMap(collectNodeIds)];
-}
-
-function collectDefaultIds(nodes: PermissionTreeItem[]): number[] {
-  return nodes.flatMap((node) => [
-    ...(node.isGrantedByDefault ? [node.id] : []),
-    ...collectDefaultIds(node.children),
-  ]);
-}
-
-function collectIdsByKeys(nodes: PermissionTreeItem[], keys: string[]): number[] {
-  const selectedKeys = new Set(keys);
-  return nodes.flatMap((node) => [
-    ...(selectedKeys.has(node.key) ? [node.id] : []),
-    ...collectIdsByKeys(node.children, keys),
-  ]);
-}
-
-function PermissionCheckbox({
-  checked,
-  indeterminate,
-  onChange,
-}: {
-  checked: boolean;
-  indeterminate: boolean;
-  onChange: (checked: boolean) => void;
-}) {
-  const ref = useRef<HTMLInputElement>(null);
-
-  useEffect(() => {
-    if (ref.current) {
-      ref.current.indeterminate = indeterminate;
-    }
-  }, [indeterminate]);
-
-  return (
-    <input
-      ref={ref}
-      type="checkbox"
-      checked={checked}
-      onChange={(event) => onChange(event.target.checked)}
-      className="size-4 rounded border-border accent-primary"
-    />
-  );
-}
-
-function PermissionTreeNodeRow({
-  node,
-  selectedIds,
-  onToggle,
-}: {
-  node: PermissionTreeItem;
-  selectedIds: Set<number>;
-  onToggle: (node: PermissionTreeItem, checked: boolean) => void;
-}) {
-  const nodeIds = collectNodeIds(node);
-  const checkedCount = nodeIds.filter((id) => selectedIds.has(id)).length;
-  const checked = checkedCount === nodeIds.length;
-  const indeterminate = checkedCount > 0 && !checked;
-
-  return (
-    <li className="space-y-2">
-      <div className="flex items-start gap-3 rounded-md border border-border/60 bg-background px-3 py-2">
-        <PermissionCheckbox
-          checked={checked}
-          indeterminate={indeterminate}
-          onChange={(isChecked) => onToggle(node, isChecked)}
-        />
-        <div className="min-w-0 flex-1">
-          <div className="flex flex-wrap items-center gap-2">
-            <span className="text-sm font-medium">{node.label}</span>
-            <Badge variant="outline" className="text-[10px] capitalize">
-              {node.type}
-            </Badge>
-          </div>
-          {node.description ? (
-            <p className="mt-1 text-xs text-muted-foreground">{node.description}</p>
-          ) : null}
-        </div>
-      </div>
-      {node.children.length > 0 ? (
-        <ul className="ml-5 space-y-2 border-l border-border/70 pl-3">
-          {node.children.map((child) => (
-            <PermissionTreeNodeRow
-              key={child.id}
-              node={child}
-              selectedIds={selectedIds}
-              onToggle={onToggle}
-            />
-          ))}
-        </ul>
-      ) : null}
-    </li>
-  );
-}
-
-function PermissionTree({
-  items,
-  selectedIds,
-  onChange,
-}: {
-  items: PermissionTreeItem[];
-  selectedIds: number[];
-  onChange: (ids: number[]) => void;
-}) {
-  const selectedSet = useMemo(() => new Set(selectedIds), [selectedIds]);
-
-  const handleToggle = (node: PermissionTreeItem, checked: boolean) => {
-    const next = new Set(selectedSet);
-    collectNodeIds(node).forEach((id) => {
-      if (checked) {
-        next.add(id);
-      } else {
-        next.delete(id);
-      }
-    });
-    onChange(Array.from(next));
-  };
-
-  if (items.length === 0) {
-    return (
-      <div className="rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground">
-        No permissions available.
-      </div>
-    );
-  }
-
-  return (
-    <ul className="space-y-2">
-      {items.map((node) => (
-        <PermissionTreeNodeRow
-          key={node.id}
-          node={node}
-          selectedIds={selectedSet}
-          onToggle={handleToggle}
-        />
-      ))}
-    </ul>
-  );
-}
+import { useRoleColumns } from './components/RoleColumns';
+import { RoleFilters } from './components/RoleFilters';
+import { RoleSheet } from './components/RoleSheet';
+import { RoleTable } from './components/RoleTable';
+import { useRoleFilters } from './hooks/useRoleFilters';
+import { useRoleForm } from './hooks/useRoleForm';
+import {
+  usePermissionsTreeQuery,
+  useRolesQuery,
+  useRoleStatusMutation,
+} from './hooks/useRoleQueries';
 
 export default function RolesPage() {
-  const queryClient = useQueryClient();
   const organizationId = useAppStore((state) => state.user?.organization_id ?? null);
-  const [skip, setSkip] = useState(0);
-  const [limit] = useState(10);
-  const [searchTerm, setSearchTerm] = useState('');
-  const [statusFilter, setStatusFilter] = useState<StatusFilter>('all');
   const [isSheetOpen, setIsSheetOpen] = useState(false);
-  const [form, setForm] = useState<RoleFormState>(emptyRoleForm);
+  const {
+    skip,
+    setSkip,
+    limit,
+    searchTerm,
+    debouncedSearchTerm,
+    setSearchTerm,
+    statusFilter,
+    setStatusFilter,
+  } = useRoleFilters();
 
-  const rolesQuery = useQuery({
-    queryKey: ['roles', { skip, limit, searchTerm, statusFilter }],
-    queryFn: () =>
-      roleService.getRoles({
-        skip,
-        limit,
-        search_term: searchTerm || undefined,
-        effective_status:
-          statusFilter === 'all' ? undefined : statusFilter === 'active' ? true : false,
-        sort_by: 'created_at',
-        sort_order: 'desc',
-      }),
+  const rolesQuery = useRolesQuery({
+    skip,
+    limit,
+    searchTerm: debouncedSearchTerm,
+    statusFilter,
   });
-
-  const permissionsQuery = useQuery({
-    queryKey: ['permissions', 'tree'],
-    queryFn: permissionService.getPermissions,
+  const permissionsQuery = usePermissionsTreeQuery();
+  const roleForm = useRoleForm({
+    organizationId,
+    permissionTree: permissionsQuery.permissionTree,
+    onSaved: () => setIsSheetOpen(false),
   });
+  const {
+    openCreate: prepareCreateRole,
+    openEdit: prepareEditRole,
+    register,
+    onSubmit,
+    roleId,
+    permissionIds,
+    setPermissionIds,
+    isSaving,
+  } = roleForm;
+  const statusMutation = useRoleStatusMutation();
+  const { mutate: updateRoleStatus, isPending: isStatusPending } = statusMutation;
 
-  const permissionTree = useMemo(
-    () => mapPermissionTree(permissionsQuery.data?.tree || []),
-    [permissionsQuery.data?.tree],
+  const openCreate = useCallback(() => {
+    prepareCreateRole();
+    setIsSheetOpen(true);
+  }, [prepareCreateRole]);
+
+  const openEdit = useCallback(
+    (role: Role) => {
+      prepareEditRole(role);
+      setIsSheetOpen(true);
+    },
+    [prepareEditRole],
   );
 
-  const saveMutation = useMutation({
-    mutationFn: () =>
-      roleService.saveRole({
-        id: form.id,
-        name: form.name.trim(),
-        display_name: form.display_name.trim(),
-        description: form.description.trim(),
-        organization_id: organizationId,
-        permission_ids: form.permission_ids,
-        is_default: false,
-      }),
-    onSuccess: () => {
-      toast.success(form.id ? 'Role updated' : 'Role created');
-      setIsSheetOpen(false);
-      setForm(emptyRoleForm);
-      queryClient.invalidateQueries({ queryKey: ['roles'] });
+  const toggleStatus = useCallback(
+    (role: Role) => {
+      updateRoleStatus(role);
     },
-    onError: () => toast.error(form.id ? 'Failed to update role' : 'Failed to create role'),
+    [updateRoleStatus],
+  );
+
+  const columns = useRoleColumns({
+    onEdit: openEdit,
+    onToggleStatus: toggleStatus,
+    isStatusPending,
   });
 
-  const statusMutation = useMutation({
-    mutationFn: (role: Role) => roleService.updateRoleStatus(role.id, !role.effective_status),
-    onSuccess: () => {
-      toast.success('Role status updated');
-      queryClient.invalidateQueries({ queryKey: ['roles'] });
-    },
-    onError: () => toast.error('Failed to update role status'),
-  });
-
-  const openCreate = () => {
-    setForm({ ...emptyRoleForm, permission_ids: collectDefaultIds(permissionTree) });
-    setIsSheetOpen(true);
-  };
-
-  const openEdit = (role: Role) => {
-    setForm({
-      id: role.id,
-      name: role.name || '',
-      display_name: role.display_name || '',
-      description: role.description || '',
-      permission_ids: collectIdsByKeys(permissionTree, role.permissions || []),
-    });
-    setIsSheetOpen(true);
-  };
-
-  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    if (!form.name.trim() || !form.display_name.trim()) {
-      toast.error('Role name and display name are required');
-      return;
-    }
-    if (form.permission_ids.length === 0) {
-      toast.error('Select at least one permission');
-      return;
-    }
-    saveMutation.mutate();
-  };
-
   const total = rolesQuery.data?.total ?? 0;
   const roles = rolesQuery.data?.items ?? [];
-  const columns: ColumnDef<Role>[] = [
-    {
-      accessorKey: 'name',
-      header: 'Name',
-      cell: ({ row }) => <span className="font-medium">{row.original.name}</span>,
-    },
-    {
-      accessorKey: 'display_name',
-      header: 'Display Name',
-    },
-    {
-      accessorKey: 'description',
-      header: 'Description',
-      cell: ({ row }) => (
-        <span className="block max-w-sm truncate text-muted-foreground">
-          {row.original.description || '-'}
-        </span>
-      ),
-    },
-    {
-      accessorKey: 'user_count',
-      header: 'Users',
-      cell: ({ row }) => row.original.user_count ?? 0,
-    },
-    {
-      accessorKey: 'effective_status',
-      header: 'Status',
-      cell: ({ row }) => (
-        <Badge variant={row.original.effective_status ? 'default' : 'secondary'}>
-          {row.original.effective_status ? 'Active' : 'Inactive'}
-        </Badge>
-      ),
-    },
-    {
-      id: 'actions',
-      header: () => <div className="text-right">Actions</div>,
-      cell: ({ row }) => {
-        const role = row.original;
-        return (
-          <div className="flex justify-end gap-2">
-            <Button variant="outline" size="sm" onClick={() => openEdit(role)}>
-              <Edit className="size-4" />
-            </Button>
-            <Button
-              variant="outline"
-              size="sm"
-              disabled={statusMutation.isPending}
-              onClick={() => statusMutation.mutate(role)}
-            >
-              <RotateCcw className="mr-2 size-4" />
-              {role.effective_status ? 'Deactivate' : 'Activate'}
-            </Button>
-          </div>
-        );
-      },
-    },
-  ];
   const toolbar = (
-    <div className="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
-      <Input
-        value={searchTerm}
-        onChange={(event) => {
-          setSearchTerm(event.target.value);
-          setSkip(0);
-        }}
-        placeholder="Search roles"
-        className="md:max-w-sm"
-      />
-      <Select
-        value={statusFilter}
-        onValueChange={(value) => {
-          setStatusFilter(value as StatusFilter);
-          setSkip(0);
-        }}
-      >
-        <SelectTrigger className="md:w-44">
-          <SelectValue />
-        </SelectTrigger>
-        <SelectContent>
-          <SelectItem value="all">All status</SelectItem>
-          <SelectItem value="active">Active</SelectItem>
-          <SelectItem value="inactive">Inactive</SelectItem>
-        </SelectContent>
-      </Select>
-    </div>
+    <RoleFilters
+      searchTerm={searchTerm}
+      statusFilter={statusFilter}
+      onSearchChange={setSearchTerm}
+      onStatusChange={setStatusFilter}
+    />
   );
 
   return (
@@ -400,109 +112,32 @@ export default function RolesPage() {
           }
         />
 
-        <DataTable
-          title="Roles"
+        <RoleTable
           columns={columns}
-          data={roles}
+          roles={roles}
           isLoading={rolesQuery.isLoading}
           toolbar={toolbar}
-          emptyTitle="No roles found."
-          pagination={{
-            skip,
-            limit,
-            totalItems: total,
-            onPageChange: setSkip,
-            onLimitChange: () => undefined,
-          }}
+          skip={skip}
+          limit={limit}
+          total={total}
+          onPageChange={setSkip}
         />
 
         <PoweredBy />
       </main>
 
-      <Sheet open={isSheetOpen} onOpenChange={setIsSheetOpen}>
-        <SheetContent className="w-full overflow-y-auto sm:max-w-2xl">
-          <SheetHeader>
-            <SheetTitle>{form.id ? 'Edit Role' : 'Create Role'}</SheetTitle>
-            <SheetDescription>
-              Assign the role details and permission access for this organization.
-            </SheetDescription>
-          </SheetHeader>
-          <form onSubmit={handleSubmit} className="flex flex-1 flex-col gap-5 px-4">
-            <div className="grid gap-4 md:grid-cols-2">
-              <div className="space-y-2">
-                <Label htmlFor="role-name">Role Name</Label>
-                <Input
-                  id="role-name"
-                  value={form.name}
-                  onChange={(event) => setForm((prev) => ({ ...prev, name: event.target.value }))}
-                  required
-                />
-              </div>
-              <div className="space-y-2">
-                <Label htmlFor="role-display-name">Display Name</Label>
-                <Input
-                  id="role-display-name"
-                  value={form.display_name}
-                  onChange={(event) =>
-                    setForm((prev) => ({ ...prev, display_name: event.target.value }))
-                  }
-                  required
-                />
-              </div>
-            </div>
-
-            <div className="space-y-2">
-              <Label htmlFor="role-description">Description</Label>
-              <textarea
-                id="role-description"
-                value={form.description}
-                onChange={(event) =>
-                  setForm((prev) => ({ ...prev, description: event.target.value }))
-                }
-                className={cn(
-                  'min-h-24 w-full rounded-md border border-input bg-background px-3 py-2 text-sm',
-                  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-                )}
-              />
-            </div>
-
-            <div className="space-y-3">
-              <div className="flex items-center justify-between gap-3">
-                <Label>Permissions</Label>
-                <span className="text-xs text-muted-foreground">
-                  {form.permission_ids.length} selected
-                </span>
-              </div>
-              {permissionsQuery.isLoading ? (
-                <div className="rounded-md border p-6 text-sm text-muted-foreground">
-                  Loading permissions...
-                </div>
-              ) : (
-                <PermissionTree
-                  items={permissionTree}
-                  selectedIds={form.permission_ids}
-                  onChange={(ids) => setForm((prev) => ({ ...prev, permission_ids: ids }))}
-                />
-              )}
-            </div>
-
-            <SheetFooter className="px-0">
-              <Button
-                type="button"
-                variant="outline"
-                onClick={() => setIsSheetOpen(false)}
-                disabled={saveMutation.isPending}
-              >
-                Cancel
-              </Button>
-              <Button type="submit" disabled={saveMutation.isPending}>
-                {saveMutation.isPending ? <Loader2 className="mr-2 size-4 animate-spin" /> : null}
-                {form.id ? 'Update Role' : 'Create Role'}
-              </Button>
-            </SheetFooter>
-          </form>
-        </SheetContent>
-      </Sheet>
+      <RoleSheet
+        open={isSheetOpen}
+        onOpenChange={setIsSheetOpen}
+        roleId={roleId}
+        register={register}
+        onSubmit={onSubmit}
+        permissionTree={permissionsQuery.permissionTree}
+        permissionIds={permissionIds}
+        onPermissionIdsChange={setPermissionIds}
+        isPermissionsLoading={permissionsQuery.isLoading}
+        isSaving={isSaving}
+      />
     </>
   );
 }

src/app/(modules)/roles/queries/roleKeys.ts

@@ -0,0 +1,9 @@
+import type { RoleListParams } from '@/types';
+
+export const roleKeys = {
+  all: ['roles'] as const,
+  lists: () => [...roleKeys.all, 'list'] as const,
+  list: (params: RoleListParams) => [...roleKeys.lists(), params] as const,
+  details: () => [...roleKeys.all, 'detail'] as const,
+  detail: (id: number) => [...roleKeys.details(), id] as const,
+};

src/app/(modules)/users/components/UserColumns.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { ColumnDef } from '@tanstack/react-table';
+import { Edit, RotateCcw } from 'lucide-react';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import type { AdministrationUser } from '@/types';
+
+function formatDate(value?: string | null) {
+  if (!value) return '-';
+  return new Intl.DateTimeFormat('en-IN', {
+    day: '2-digit',
+    month: 'short',
+    year: 'numeric',
+  }).format(new Date(value));
+}
+
+interface UseUserColumnsParams {
+  onEdit: (user: AdministrationUser) => void;
+  onToggleStatus: (user: AdministrationUser) => void;
+  pendingUserId?: number;
+}
+
+export function useUserColumns({
+  onEdit,
+  onToggleStatus,
+  pendingUserId,
+}: UseUserColumnsParams): ColumnDef<AdministrationUser>[] {
+  return useMemo(
+    () => [
+      {
+        accessorKey: 'first_name',
+        header: 'Name',
+        cell: ({ row }) => (
+          <span className="font-medium">
+            {[row.original.first_name, row.original.last_name].filter(Boolean).join(' ') ||
+              row.original.username}
+          </span>
+        ),
+      },
+      {
+        accessorKey: 'email',
+        header: 'Email',
+      },
+      {
+        accessorKey: 'phone_number',
+        header: 'Phone',
+        cell: ({ row }) => row.original.phone_number || '-',
+      },
+      {
+        accessorKey: 'roles',
+        header: 'Roles',
+        cell: ({ row }) => (
+          <div className="flex flex-wrap gap-1">
+            {row.original.roles?.length ? (
+              row.original.roles.map((role) => (
+                <Badge key={role.id ?? role.name} variant="outline">
+                  {role.display_name || role.name}
+                </Badge>
+              ))
+            ) : (
+              <span className="text-muted-foreground">-</span>
+            )}
+          </div>
+        ),
+      },
+      {
+        accessorKey: 'created_at',
+        header: 'Created',
+        cell: ({ row }) => formatDate(row.original.created_at),
+      },
+      {
+        accessorKey: 'effective_status',
+        header: 'Status',
+        cell: ({ row }) => (
+          <Badge variant={row.original.effective_status === 'active' ? 'default' : 'secondary'}>
+            {row.original.effective_status}
+          </Badge>
+        ),
+      },
+      {
+        id: 'actions',
+        header: () => <div className="text-right">Actions</div>,
+        cell: ({ row }) => {
+          const user = row.original;
+          return (
+            <div className="flex justify-end gap-2">
+              <Button variant="outline" size="sm" onClick={() => onEdit(user)}>
+                <Edit className="size-4" />
+              </Button>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={pendingUserId === user.id || user.effective_status === 'pending'}
+                onClick={() => onToggleStatus(user)}
+              >
+                <RotateCcw className="mr-2 size-4" />
+                {user.effective_status === 'active' ? 'Deactivate' : 'Activate'}
+              </Button>
+            </div>
+          );
+        },
+      },
+    ],
+    [onEdit, onToggleStatus, pendingUserId],
+  );
+}

src/app/(modules)/users/components/UserFilters.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { Input } from '@/components/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import type { StatusFilter } from '../hooks/useUserFilters';
+
+interface UserFiltersProps {
+  searchTerm: string;
+  statusFilter: StatusFilter;
+  onSearchChange: (value: string) => void;
+  onStatusChange: (value: StatusFilter) => void;
+}
+
+export function UserFilters({
+  searchTerm,
+  statusFilter,
+  onSearchChange,
+  onStatusChange,
+}: UserFiltersProps) {
+  return (
+    <div className="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+      <Input
+        value={searchTerm}
+        onChange={(event) => onSearchChange(event.target.value)}
+        placeholder="Search users"
+        className="md:max-w-sm"
+      />
+      <Select value={statusFilter} onValueChange={(value) => onStatusChange(value as StatusFilter)}>
+        <SelectTrigger className="md:w-44">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="all">All status</SelectItem>
+          <SelectItem value="active">Active</SelectItem>
+          <SelectItem value="inactive">Inactive</SelectItem>
+          <SelectItem value="pending">Pending</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}

src/app/(modules)/users/components/UserSheet.tsx

@@ -0,0 +1,142 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+import type { UseFormRegister } from 'react-hook-form';
+import { Loader2 } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import type { Role } from '@/types';
+import type { UserFormValues } from '../hooks/useUserForm';
+
+interface UserSheetProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  userId?: number;
+  register: UseFormRegister<UserFormValues>;
+  onSubmit: ComponentProps<'form'>['onSubmit'];
+  roleId: string;
+  onRoleChange: (roleId: string) => void;
+  roles: Role[];
+  isRolesLoading: boolean;
+  isSaving: boolean;
+}
+
+export function UserSheet({
+  open,
+  onOpenChange,
+  userId,
+  register,
+  onSubmit,
+  roleId,
+  onRoleChange,
+  roles,
+  isRolesLoading,
+  isSaving,
+}: UserSheetProps) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-h-[calc(100vh-2rem)] overflow-y-auto sm:max-w-xl">
+        <DialogHeader>
+          <DialogTitle>{userId ? 'Edit User' : 'Create User'}</DialogTitle>
+          <DialogDescription>Assign user details and a role.</DialogDescription>
+        </DialogHeader>
+        <form onSubmit={onSubmit} className="flex flex-1 flex-col gap-5 px-4">
+          <div className="grid gap-4 md:grid-cols-2">
+            <div className="space-y-2">
+              <Label htmlFor="first-name">First Name</Label>
+              <Input
+                id="first-name"
+                placeholder="Enter first name"
+                {...register('first_name', { required: true })}
+                required
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="last-name">Last Name</Label>
+              <Input
+                id="last-name"
+                placeholder="Enter last name"
+                {...register('last_name', { required: true })}
+                required
+              />
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              placeholder="name@example.com"
+              {...register('email', { required: true })}
+              required
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="phone-number">Phone Number</Label>
+            <Input
+              id="phone-number"
+              placeholder="Enter phone number"
+              {...register('phone_number')}
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label>Role</Label>
+            <Select value={roleId} onValueChange={onRoleChange}>
+              <SelectTrigger>
+                <SelectValue placeholder={isRolesLoading ? 'Loading roles...' : 'Select role'} />
+              </SelectTrigger>
+              <SelectContent>
+                {roles.map((role) => (
+                  <SelectItem key={role.id} value={String(role.id)}>
+                    {role.display_name || role.name}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <input
+              type="hidden"
+              {...register('role_id', { required: true })}
+              value={roleId}
+              readOnly
+            />
+          </div>
+
+          <DialogFooter className="px-0">
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => onOpenChange(false)}
+              disabled={isSaving}
+            >
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSaving}>
+              {isSaving ? <Loader2 className="mr-2 size-4 animate-spin" /> : null}
+              {userId ? 'Update User' : 'Create User'}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/app/(modules)/users/components/UserStats.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+interface UserStatsProps {
+  total: number;
+  activeCount: number;
+  inactiveCount: number;
+  pendingCount: number;
+}
+
+export function UserStats({ total, activeCount, inactiveCount, pendingCount }: UserStatsProps) {
+  const stats = [
+    { label: 'Total', value: total },
+    { label: 'Active', value: activeCount },
+    { label: 'Inactive', value: inactiveCount },
+    { label: 'Pending', value: pendingCount },
+  ];
+
+  return (
+    <div className="grid gap-3 md:grid-cols-4">
+      {stats.map((stat) => (
+        <div key={stat.label} className="rounded-lg border bg-card p-4">
+          <p className="text-xs text-muted-foreground">{stat.label}</p>
+          <p className="mt-1 text-2xl font-semibold">{stat.value}</p>
+        </div>
+      ))}
+    </div>
+  );
+}

src/app/(modules)/users/components/UserTable.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import type { ColumnDef } from '@tanstack/react-table';
+
+import { DataTable } from '@/components/data-table';
+import type { AdministrationUser } from '@/types';
+
+interface UserTableProps {
+  columns: ColumnDef<AdministrationUser>[];
+  users: AdministrationUser[];
+  isLoading: boolean;
+  toolbar: ReactNode;
+  skip: number;
+  limit: number;
+  total: number;
+  onPageChange: (skip: number) => void;
+}
+
+export function UserTable({
+  columns,
+  users,
+  isLoading,
+  toolbar,
+  skip,
+  limit,
+  total,
+  onPageChange,
+}: UserTableProps) {
+  return (
+    <DataTable
+      title="Users"
+      columns={columns}
+      data={users}
+      isLoading={isLoading}
+      toolbar={toolbar}
+      emptyTitle="No users found."
+      pagination={{
+        skip,
+        limit,
+        totalItems: total,
+        onPageChange,
+        onLimitChange: () => undefined,
+      }}
+    />
+  );
+}

src/app/(modules)/users/hooks/useUserFilters.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import { useDebounce } from '@/hooks/useDebounce';
+import type { UserStatus } from '@/types';
+import { useCallback, useState } from 'react';
+
+export type StatusFilter = 'all' | UserStatus;
+
+export function useUserFilters() {
+  const [skip, setSkip] = useState(0);
+  const [limit] = useState(10);
+  const [searchTerm, setSearchTermValue] = useState('');
+  const [statusFilter, setStatusFilterValue] = useState<StatusFilter>('all');
+  const debouncedSearchTerm = useDebounce(searchTerm.trim(), 400);
+
+  const setSearchTerm = useCallback((value: string) => {
+    setSearchTermValue(value);
+    setSkip(0);
+  }, []);
+
+  const setStatusFilter = useCallback((value: StatusFilter) => {
+    setStatusFilterValue(value);
+    setSkip(0);
+  }, []);
+
+  return {
+    skip,
+    setSkip,
+    limit,
+    searchTerm,
+    debouncedSearchTerm,
+    setSearchTerm,
+    statusFilter,
+    setStatusFilter,
+  };
+}

src/app/(modules)/users/hooks/useUserForm.ts

@@ -0,0 +1,99 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useForm, useWatch } from 'react-hook-form';
+import { toast } from 'sonner';
+
+import type { AdministrationUser } from '@/types';
+import { useSaveUserMutation } from './useUserMutations';
+
+export interface UserFormValues {
+  id?: number;
+  first_name: string;
+  last_name: string;
+  email: string;
+  phone_number: string;
+  role_id: string;
+}
+
+const defaultValues: UserFormValues = {
+  first_name: '',
+  last_name: '',
+  email: '',
+  phone_number: '',
+  role_id: '',
+};
+
+export function useUserForm({ onSaved }: { onSaved: () => void }) {
+  const {
+    control,
+    register,
+    handleSubmit: submitForm,
+    reset,
+    setValue,
+    formState: { isSubmitting, errors },
+  } = useForm<UserFormValues>({
+    defaultValues,
+  });
+  const saveMutation = useSaveUserMutation({
+    onSaved: () => {
+      reset(defaultValues);
+      onSaved();
+    },
+  });
+
+  const userId = useWatch({ control, name: 'id' });
+  const roleId = useWatch({ control, name: 'role_id' }) || '';
+
+  const handleSubmit = submitForm(
+    (values) => saveMutation.mutate(values),
+    (formErrors) => {
+      if (formErrors.first_name || formErrors.last_name || formErrors.email) {
+        toast.error('First name, last name and email are required');
+        return;
+      }
+      if (formErrors.role_id) {
+        toast.error('Select a role');
+      }
+    },
+  );
+
+  const openCreate = useCallback(() => {
+    reset(defaultValues);
+  }, [reset]);
+
+  const openEdit = useCallback(
+    (user: AdministrationUser) => {
+      const selectedRoleId = user.role_ids?.[0] ?? user.roles?.[0]?.id;
+      reset({
+        id: user.id,
+        first_name: user.first_name || '',
+        last_name: user.last_name || '',
+        email: user.email || '',
+        phone_number: user.phone_number || '',
+        role_id: selectedRoleId ? String(selectedRoleId) : '',
+      });
+    },
+    [reset],
+  );
+
+  const setRoleId = useCallback(
+    (value: string) => {
+      setValue('role_id', value, { shouldDirty: true, shouldValidate: true });
+    },
+    [setValue],
+  );
+
+  return {
+    register,
+    handleSubmit,
+    reset,
+    openCreate,
+    openEdit,
+    setRoleId,
+    roleId,
+    userId,
+    errors,
+    isSaving: isSubmitting || saveMutation.isPending,
+  };
+}

src/app/(modules)/users/hooks/useUserMutations.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { userService } from '@/services/api';
+import type { AdministrationUser, UserStatus } from '@/types';
+import { userKeys } from '../queries/userKeys';
+import type { UserFormValues } from './useUserForm';
+
+function getNextStatus(status: UserStatus): 'active' | 'inactive' {
+  return status === 'active' ? 'inactive' : 'active';
+}
+
+export function useSaveUserMutation({ onSaved }: { onSaved: () => void }) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (values: UserFormValues) =>
+      userService.saveUser({
+        id: values.id,
+        email: values.email.trim(),
+        first_name: values.first_name.trim(),
+        last_name: values.last_name.trim(),
+        phone_number: values.phone_number.trim() || undefined,
+        roles: [Number(values.role_id)],
+      }),
+    onSuccess: (_data, values) => {
+      toast.success(values.id ? 'User updated' : 'User created');
+      onSaved();
+      queryClient.invalidateQueries({ queryKey: userKeys.all });
+    },
+    onError: (_error, values) => {
+      toast.error(values.id ? 'Failed to update user' : 'Failed to create user');
+    },
+  });
+}
+
+export function useUserStatusMutation() {
+  const queryClient = useQueryClient();
+  const mutation = useMutation({
+    mutationFn: (user: AdministrationUser) =>
+      userService.updateUserStatus(user.id, getNextStatus(user.effective_status)),
+    onSuccess: () => {
+      toast.success('User status updated');
+      queryClient.invalidateQueries({ queryKey: userKeys.all });
+    },
+    onError: () => toast.error('Failed to update user status'),
+  });
+
+  return {
+    ...mutation,
+    pendingUserId: mutation.isPending ? mutation.variables?.id : undefined,
+  };
+}

src/app/(modules)/users/hooks/useUserQueries.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+
+import { roleService, userService } from '@/services/api';
+import type { RoleListParams, UserListParams } from '@/types';
+import { roleKeys } from '../../roles/queries/roleKeys';
+import { userKeys } from '../queries/userKeys';
+import type { StatusFilter } from './useUserFilters';
+
+interface UseUsersQueryParams {
+  skip: number;
+  limit: number;
+  searchTerm: string;
+  statusFilter: StatusFilter;
+}
+
+const roleLookupParams: RoleListParams = {
+  skip: 0,
+  limit: 100,
+  effective_status: true,
+  sort_by: 'display_name',
+  sort_order: 'asc',
+};
+
+function buildUserListParams({
+  skip,
+  limit,
+  searchTerm,
+  statusFilter,
+}: UseUsersQueryParams): UserListParams {
+  return {
+    skip,
+    limit,
+    search_term: searchTerm || undefined,
+    effective_status: statusFilter === 'all' ? undefined : statusFilter,
+    sort_by: 'created_at',
+    sort_order: 'desc',
+  };
+}
+
+export function useUsersQuery(params: UseUsersQueryParams) {
+  const { skip, limit, searchTerm, statusFilter } = params;
+  const listParams = useMemo(
+    () => buildUserListParams({ skip, limit, searchTerm, statusFilter }),
+    [limit, searchTerm, skip, statusFilter],
+  );
+
+  return useQuery({
+    queryKey: userKeys.list(listParams),
+    queryFn: () => userService.getUsers(listParams),
+  });
+}
+
+export function useRoleLookupQuery(enabled: boolean) {
+  return useQuery({
+    queryKey: roleKeys.list(roleLookupParams),
+    queryFn: () => roleService.getRoles(roleLookupParams),
+    enabled,
+    staleTime: 5 * 60 * 1000,
+    gcTime: 30 * 60 * 1000,
+  });
+}

src/app/(modules)/users/page.tsx

@@ -1,270 +1,98 @@
 'use client';
 
-import { FormEvent, useMemo, useState } from 'react';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { Edit, Loader2, Plus, RotateCcw, Users } from 'lucide-react';
-import { toast } from 'sonner';
-import type { ColumnDef } from '@tanstack/react-table';
+import { useCallback, useMemo, useState } from 'react';
+import { Plus, Users } from 'lucide-react';
 
-import { DataTable } from '@/components/data-table';
 import { PageHeader } from '@/components/page-header';
 import { PoweredBy } from '@/components/powered-by';
-import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
-import { Input } from '@/components/ui/input';
-import { Label } from '@/components/ui/label';
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import {
-  Sheet,
-  SheetContent,
-  SheetDescription,
-  SheetFooter,
-  SheetHeader,
-  SheetTitle,
-} from '@/components/ui/sheet';
-import { roleService, userService } from '@/services/api';
-import type { AdministrationUser, UserStatus } from '@/types';
+import type { AdministrationUser } from '@/types';
 
-type StatusFilter = 'all' | UserStatus;
-
-interface UserFormState {
-  id?: number;
-  first_name: string;
-  last_name: string;
-  email: string;
-  phone_number: string;
-  role_id: string;
-}
-
-const emptyUserForm: UserFormState = {
-  first_name: '',
-  last_name: '',
-  email: '',
-  phone_number: '',
-  role_id: '',
-};
-
-function formatDate(value?: string | null) {
-  if (!value) return '-';
-  return new Intl.DateTimeFormat('en-IN', {
-    day: '2-digit',
-    month: 'short',
-    year: 'numeric',
-  }).format(new Date(value));
-}
-
-function getNextStatus(status: UserStatus): 'active' | 'inactive' {
-  return status === 'active' ? 'inactive' : 'active';
-}
+import { useUserColumns } from './components/UserColumns';
+import { UserFilters } from './components/UserFilters';
+import { UserSheet } from './components/UserSheet';
+import { UserStats } from './components/UserStats';
+import { UserTable } from './components/UserTable';
+import { useUserFilters } from './hooks/useUserFilters';
+import { useUserForm } from './hooks/useUserForm';
+import { useUserStatusMutation } from './hooks/useUserMutations';
+import { useRoleLookupQuery, useUsersQuery } from './hooks/useUserQueries';
 
 export default function UsersPage() {
-  const queryClient = useQueryClient();
-  const [skip, setSkip] = useState(0);
-  const [limit] = useState(10);
-  const [searchTerm, setSearchTerm] = useState('');
-  const [statusFilter, setStatusFilter] = useState<StatusFilter>('all');
   const [isSheetOpen, setIsSheetOpen] = useState(false);
-  const [form, setForm] = useState<UserFormState>(emptyUserForm);
+  const {
+    skip,
+    setSkip,
+    limit,
+    searchTerm,
+    debouncedSearchTerm,
+    setSearchTerm,
+    statusFilter,
+    setStatusFilter,
+  } = useUserFilters();
 
-  const usersQuery = useQuery({
-    queryKey: ['users', { skip, limit, searchTerm, statusFilter }],
-    queryFn: () =>
-      userService.getUsers({
-        skip,
-        limit,
-        search_term: searchTerm || undefined,
-        effective_status: statusFilter === 'all' ? undefined : statusFilter,
-        sort_by: 'created_at',
-        sort_order: 'desc',
-      }),
+  const usersQuery = useUsersQuery({
+    skip,
+    limit,
+    searchTerm: debouncedSearchTerm,
+    statusFilter,
   });
-
-  const rolesQuery = useQuery({
-    queryKey: ['roles', 'lookup'],
-    queryFn: () =>
-      roleService.getRoles({
-        skip: 0,
-        limit: 100,
-        effective_status: true,
-        sort_by: 'display_name',
-        sort_order: 'asc',
-      }),
+  const rolesQuery = useRoleLookupQuery(isSheetOpen);
+  const userForm = useUserForm({
+    onSaved: () => setIsSheetOpen(false),
   });
+  const {
+    openCreate: prepareCreateUser,
+    openEdit: prepareEditUser,
+    register,
+    handleSubmit,
+    userId,
+    roleId,
+    setRoleId,
+    isSaving,
+  } = userForm;
+  const statusMutation = useUserStatusMutation();
+  const { mutate: updateUserStatus, pendingUserId } = statusMutation;
 
-  const roleOptions = useMemo(() => rolesQuery.data?.items || [], [rolesQuery.data?.items]);
-
-  const saveMutation = useMutation({
-    mutationFn: () =>
-      userService.saveUser({
-        id: form.id,
-        email: form.email.trim(),
-        first_name: form.first_name.trim(),
-        last_name: form.last_name.trim(),
-        phone_number: form.phone_number.trim() || undefined,
-        roles: [Number(form.role_id)],
-      }),
-    onSuccess: () => {
-      toast.success(form.id ? 'User updated' : 'User created');
-      setIsSheetOpen(false);
-      setForm(emptyUserForm);
-      queryClient.invalidateQueries({ queryKey: ['users'] });
-    },
-    onError: () => toast.error(form.id ? 'Failed to update user' : 'Failed to create user'),
-  });
-
-  const statusMutation = useMutation({
-    mutationFn: (user: AdministrationUser) =>
-      userService.updateUserStatus(user.id, getNextStatus(user.effective_status)),
-    onSuccess: () => {
-      toast.success('User status updated');
-      queryClient.invalidateQueries({ queryKey: ['users'] });
-    },
-    onError: () => toast.error('Failed to update user status'),
-  });
-
-  const openCreate = () => {
-    setForm(emptyUserForm);
+  const openCreate = useCallback(() => {
+    prepareCreateUser();
     setIsSheetOpen(true);
-  };
+  }, [prepareCreateUser]);
 
-  const openEdit = (user: AdministrationUser) => {
-    const roleId = user.role_ids?.[0] ?? user.roles?.[0]?.id;
-    setForm({
-      id: user.id,
-      first_name: user.first_name || '',
-      last_name: user.last_name || '',
-      email: user.email || '',
-      phone_number: user.phone_number || '',
-      role_id: roleId ? String(roleId) : '',
-    });
-    setIsSheetOpen(true);
-  };
+  const openEdit = useCallback(
+    (user: AdministrationUser) => {
+      prepareEditUser(user);
+      setIsSheetOpen(true);
+    },
+    [prepareEditUser],
+  );
 
-  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    if (!form.first_name.trim() || !form.last_name.trim() || !form.email.trim()) {
-      toast.error('First name, last name and email are required');
-      return;
-    }
-    if (!form.role_id) {
-      toast.error('Select a role');
-      return;
-    }
-    saveMutation.mutate();
-  };
+  const toggleStatus = useCallback(
+    (user: AdministrationUser) => {
+      updateUserStatus(user);
+    },
+    [updateUserStatus],
+  );
+
+  const columns = useUserColumns({
+    onEdit: openEdit,
+    onToggleStatus: toggleStatus,
+    pendingUserId,
+  });
 
-  const users = usersQuery.data?.items ?? [];
   const total = usersQuery.data?.total ?? 0;
-  const columns: ColumnDef<AdministrationUser>[] = [
-    {
-      accessorKey: 'first_name',
-      header: 'Name',
-      cell: ({ row }) => (
-        <span className="font-medium">
-          {[row.original.first_name, row.original.last_name].filter(Boolean).join(' ') ||
-            row.original.username}
-        </span>
-      ),
-    },
-    {
-      accessorKey: 'email',
-      header: 'Email',
-    },
-    {
-      accessorKey: 'phone_number',
-      header: 'Phone',
-      cell: ({ row }) => row.original.phone_number || '-',
-    },
-    {
-      accessorKey: 'roles',
-      header: 'Roles',
-      cell: ({ row }) => (
-        <div className="flex flex-wrap gap-1">
-          {row.original.roles?.length ? (
-            row.original.roles.map((role) => (
-              <Badge key={role.id ?? role.name} variant="outline">
-                {role.display_name || role.name}
-              </Badge>
-            ))
-          ) : (
-            <span className="text-muted-foreground">-</span>
-          )}
-        </div>
-      ),
-    },
-    {
-      accessorKey: 'created_at',
-      header: 'Created',
-      cell: ({ row }) => formatDate(row.original.created_at),
-    },
-    {
-      accessorKey: 'effective_status',
-      header: 'Status',
-      cell: ({ row }) => (
-        <Badge variant={row.original.effective_status === 'active' ? 'default' : 'secondary'}>
-          {row.original.effective_status}
-        </Badge>
-      ),
-    },
-    {
-      id: 'actions',
-      header: () => <div className="text-right">Actions</div>,
-      cell: ({ row }) => {
-        const user = row.original;
-        return (
-          <div className="flex justify-end gap-2">
-            <Button variant="outline" size="sm" onClick={() => openEdit(user)}>
-              <Edit className="size-4" />
-            </Button>
-            <Button
-              variant="outline"
-              size="sm"
-              disabled={statusMutation.isPending || user.effective_status === 'pending'}
-              onClick={() => statusMutation.mutate(user)}
-            >
-              <RotateCcw className="mr-2 size-4" />
-              {user.effective_status === 'active' ? 'Deactivate' : 'Activate'}
-            </Button>
-          </div>
-        );
-      },
-    },
-  ];
-  const toolbar = (
-    <div className="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
-      <Input
-        value={searchTerm}
-        onChange={(event) => {
-          setSearchTerm(event.target.value);
-          setSkip(0);
-        }}
-        placeholder="Search users"
-        className="md:max-w-sm"
+  const users = usersQuery.data?.items ?? [];
+  const roleOptions = rolesQuery.data?.items ?? [];
+  const toolbar = useMemo(
+    () => (
+      <UserFilters
+        searchTerm={searchTerm}
+        statusFilter={statusFilter}
+        onSearchChange={setSearchTerm}
+        onStatusChange={setStatusFilter}
       />
-      <Select
-        value={statusFilter}
-        onValueChange={(value) => {
-          setStatusFilter(value as StatusFilter);
-          setSkip(0);
-        }}
-      >
-        <SelectTrigger className="md:w-44">
-          <SelectValue />
-        </SelectTrigger>
-        <SelectContent>
-          <SelectItem value="all">All status</SelectItem>
-          <SelectItem value="active">Active</SelectItem>
-          <SelectItem value="inactive">Inactive</SelectItem>
-          <SelectItem value="pending">Pending</SelectItem>
-        </SelectContent>
-      </Select>
-    </div>
+    ),
+    [searchTerm, setSearchTerm, setStatusFilter, statusFilter],
   );
 
   return (
@@ -282,134 +110,39 @@ export default function UsersPage() {
           }
         />
 
-        <div className="grid gap-3 md:grid-cols-4">
-          <div className="rounded-lg border bg-card p-4">
-            <p className="text-xs text-muted-foreground">Total</p>
-            <p className="mt-1 text-2xl font-semibold">{total}</p>
-          </div>
-          <div className="rounded-lg border bg-card p-4">
-            <p className="text-xs text-muted-foreground">Active</p>
-            <p className="mt-1 text-2xl font-semibold">{usersQuery.data?.active_count ?? 0}</p>
-          </div>
-          <div className="rounded-lg border bg-card p-4">
-            <p className="text-xs text-muted-foreground">Inactive</p>
-            <p className="mt-1 text-2xl font-semibold">{usersQuery.data?.inactive_count ?? 0}</p>
-          </div>
-          <div className="rounded-lg border bg-card p-4">
-            <p className="text-xs text-muted-foreground">Pending</p>
-            <p className="mt-1 text-2xl font-semibold">{usersQuery.data?.pending_count ?? 0}</p>
-          </div>
-        </div>
+        <UserStats
+          total={total}
+          activeCount={usersQuery.data?.active_count ?? 0}
+          inactiveCount={usersQuery.data?.inactive_count ?? 0}
+          pendingCount={usersQuery.data?.pending_count ?? 0}
+        />
 
-        <DataTable
-          title="Users"
+        <UserTable
           columns={columns}
-          data={users}
+          users={users}
           isLoading={usersQuery.isLoading}
           toolbar={toolbar}
-          emptyTitle="No users found."
-          pagination={{
-            skip,
-            limit,
-            totalItems: total,
-            onPageChange: setSkip,
-            onLimitChange: () => undefined,
-          }}
+          skip={skip}
+          limit={limit}
+          total={total}
+          onPageChange={setSkip}
         />
 
         <PoweredBy />
       </main>
 
-      <Sheet open={isSheetOpen} onOpenChange={setIsSheetOpen}>
-        <SheetContent className="w-full overflow-y-auto sm:max-w-xl">
-          <SheetHeader>
-            <SheetTitle>{form.id ? 'Edit User' : 'Create User'}</SheetTitle>
-            <SheetDescription>Assign user details and a role.</SheetDescription>
-          </SheetHeader>
-          <form onSubmit={handleSubmit} className="flex flex-1 flex-col gap-5 px-4">
-            <div className="grid gap-4 md:grid-cols-2">
-              <div className="space-y-2">
-                <Label htmlFor="first-name">First Name</Label>
-                <Input
-                  id="first-name"
-                  value={form.first_name}
-                  onChange={(event) =>
-                    setForm((prev) => ({ ...prev, first_name: event.target.value }))
-                  }
-                  required
-                />
-              </div>
-              <div className="space-y-2">
-                <Label htmlFor="last-name">Last Name</Label>
-                <Input
-                  id="last-name"
-                  value={form.last_name}
-                  onChange={(event) =>
-                    setForm((prev) => ({ ...prev, last_name: event.target.value }))
-                  }
-                  required
-                />
-              </div>
-            </div>
-
-            <div className="space-y-2">
-              <Label htmlFor="email">Email</Label>
-              <Input
-                id="email"
-                type="email"
-                value={form.email}
-                onChange={(event) => setForm((prev) => ({ ...prev, email: event.target.value }))}
-                required
-              />
-            </div>
-
-            <div className="space-y-2">
-              <Label htmlFor="phone-number">Phone Number</Label>
-              <Input
-                id="phone-number"
-                value={form.phone_number}
-                onChange={(event) =>
-                  setForm((prev) => ({ ...prev, phone_number: event.target.value }))
-                }
-              />
-            </div>
-
-            <div className="space-y-2">
-              <Label>Role</Label>
-              <Select
-                value={form.role_id}
-                onValueChange={(value) => setForm((prev) => ({ ...prev, role_id: value }))}
-              >
-                <SelectTrigger>
-                  <SelectValue placeholder={rolesQuery.isLoading ? 'Loading roles...' : 'Select role'} />
-                </SelectTrigger>
-                <SelectContent>
-                  {roleOptions.map((role) => (
-                    <SelectItem key={role.id} value={String(role.id)}>
-                      {role.display_name || role.name}
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-            </div>
-
-            <SheetFooter className="px-0">
-              <Button
-                type="button"
-                variant="outline"
-                onClick={() => setIsSheetOpen(false)}
-                disabled={saveMutation.isPending}
-              >
-                Cancel
-              </Button>
-              <Button type="submit" disabled={saveMutation.isPending}>
-                {saveMutation.isPending ? <Loader2 className="mr-2 size-4 animate-spin" /> : null}
-                {form.id ? 'Update User' : 'Create User'}
-              </Button>
-            </SheetFooter>
-          </form>
-        </SheetContent>
-      </Sheet>
+      <UserSheet
+        open={isSheetOpen}
+        onOpenChange={setIsSheetOpen}
+        userId={userId}
+        register={register}
+        onSubmit={handleSubmit}
+        roleId={roleId}
+        onRoleChange={setRoleId}
+        roles={roleOptions}
+        isRolesLoading={rolesQuery.isLoading}
+        isSaving={isSaving}
+      />
     </>
   );
 }

src/app/(modules)/users/queries/userKeys.ts

@@ -0,0 +1,10 @@
+import type { UserListParams } from '@/types';
+
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (filters: UserListParams) => [...userKeys.lists(), filters] as const,
+  details: () => [...userKeys.all, 'detail'] as const,
+  detail: (id: number) => [...userKeys.details(), id] as const,
+  stats: () => [...userKeys.all, 'stats'] as const,
+};

src/components/data-table/TableHeader.tsx

@@ -5,14 +5,14 @@ import { Table } from '@tanstack/react-table';
 
 const TableHeader = <TData, _>({ table }: { table: Table<TData> }) => {
   return (
-    <ShadTableHeader>
+    <ShadTableHeader className="sticky top-0 z-10 bg-card">
       {table.getHeaderGroups().map((headerGroup) => (
         <TableRow key={headerGroup.id}>
           {headerGroup.headers.map((header) => {
             return (
               <TableHead
                 key={header.id}
-                className="h-10 px-2 text-foreground"
+                className="h-10 px-2 text-foreground bg-card"
               >
                 {header.isPlaceholder ? null : (
                   <div className="flex items-center gap-2">

src/components/data-table/index.tsx

@@ -135,7 +135,7 @@ export function DataTable<TData, TValue>({
   return (
     <section className="space-y-4 rounded-lg border bg-card p-4">
         <TopHeader
-          title={title}
+          title={onAddNew ? title : undefined}
           itemCount={pagination?.totalItems ?? data.length}
           onAddNew={onAddNew}
           addButtonText={addButtonText}

src/components/permission-tree.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import { Badge } from '@/components/ui/badge';
+import { CheckboxTree } from '@/components/ui/tree';
+import type { PermissionTreeItem, PermissionTreeNode } from '@/types';
+
+export function mapPermissionTree(nodes: PermissionTreeNode[]): PermissionTreeItem[] {
+  return nodes.map((node) => ({
+    id: node.id,
+    key: node.slug || node.name,
+    label: node.display_name || node.name,
+    description: node.description,
+    type: node.type,
+    isGrantedByDefault: Boolean(node.is_granted_by_default),
+    children: mapPermissionTree(node.children || []),
+  }));
+}
+
+export function collectDefaultPermissionIds(nodes: PermissionTreeItem[]): number[] {
+  return nodes.flatMap((node) => [
+    ...(node.isGrantedByDefault ? [node.id] : []),
+    ...collectDefaultPermissionIds(node.children),
+  ]);
+}
+
+export function collectPermissionIdsByKeys(nodes: PermissionTreeItem[], keys: string[]): number[] {
+  const selectedKeys = new Set(keys);
+  return nodes.flatMap((node) => [
+    ...(selectedKeys.has(node.key) ? [node.id] : []),
+    ...collectPermissionIdsByKeys(node.children, keys),
+  ]);
+}
+
+export function PermissionTree({
+  items,
+  selectedIds,
+  onChange,
+}: {
+  items: PermissionTreeItem[];
+  selectedIds: number[];
+  onChange: (ids: number[]) => void;
+}) {
+  return (
+    <CheckboxTree
+      items={items}
+      selectedIds={selectedIds}
+      onSelectedIdsChange={onChange}
+      emptyMessage="No permissions available."
+      renderMeta={(item) => (
+        <Badge variant="outline" className="text-[10px] capitalize">
+          {item.type}
+        </Badge>
+      )}
+    />
+  );
+}

src/components/ui/tree.tsx

@@ -0,0 +1,161 @@
+'use client';
+
+import { ChevronDown } from 'lucide-react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+
+export interface TreeItem {
+  id: number;
+  label: string;
+  description?: string;
+  children: TreeItem[];
+}
+
+export function collectTreeItemIds<TItem extends TreeItem>(item: TItem): number[] {
+  return [item.id, ...item.children.flatMap((child) => collectTreeItemIds(child as TItem))];
+}
+
+function TreeCheckbox({
+  checked,
+  indeterminate,
+  onChange,
+}: {
+  checked: boolean;
+  indeterminate: boolean;
+  onChange: (checked: boolean) => void;
+}) {
+  const ref = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    if (ref.current) {
+      ref.current.indeterminate = indeterminate;
+    }
+  }, [indeterminate]);
+
+  return (
+    <input
+      ref={ref}
+      type="checkbox"
+      checked={checked}
+      onChange={(event) => onChange(event.target.checked)}
+      className="size-4 rounded border-border accent-primary"
+    />
+  );
+}
+
+function CheckboxTreeNode<TItem extends TreeItem>({
+  item,
+  selectedIds,
+  onToggle,
+  renderMeta,
+}: {
+  item: TItem;
+  selectedIds: Set<number>;
+  onToggle: (item: TItem, checked: boolean) => void;
+  renderMeta?: (item: TItem) => ReactNode;
+}) {
+  const [isExpanded, setIsExpanded] = useState(true);
+  const itemIds = collectTreeItemIds(item);
+  const selectedCount = itemIds.filter((id) => selectedIds.has(id)).length;
+  const checked = selectedCount === itemIds.length;
+  const indeterminate = selectedCount > 0 && !checked;
+  const hasChildren = item.children.length > 0;
+
+  return (
+    <li className="space-y-2">
+      <div className="flex items-start gap-2 rounded-md border border-border/60 bg-background px-3 py-2">
+        {hasChildren ? (
+          <button
+            type="button"
+            onClick={() => setIsExpanded((current) => !current)}
+            aria-label={isExpanded ? `Collapse ${item.label}` : `Expand ${item.label}`}
+            className="mt-0.5 inline-flex size-5 shrink-0 items-center justify-center rounded text-muted-foreground transition hover:bg-muted hover:text-foreground"
+          >
+            <ChevronDown
+              className={`size-4 transition-transform ${isExpanded ? '' : '-rotate-90'}`}
+            />
+          </button>
+        ) : (
+          <span className="size-5 shrink-0" aria-hidden="true" />
+        )}
+        <TreeCheckbox
+          checked={checked}
+          indeterminate={indeterminate}
+          onChange={(isChecked) => onToggle(item, isChecked)}
+        />
+        <div className="min-w-0 flex-1 leading-none">
+          <div className="flex min-h-5 flex-wrap items-center gap-2">
+            <span className="text-sm font-medium leading-5">{item.label}</span>
+            {renderMeta?.(item)}
+          </div>
+          {item.description ? (
+            <p className="mt-1 text-xs text-muted-foreground">{item.description}</p>
+          ) : null}
+        </div>
+      </div>
+      {hasChildren && isExpanded ? (
+        <ul className="ml-5 space-y-2 border-l border-border/70 pl-3">
+          {item.children.map((child) => (
+            <CheckboxTreeNode
+              key={child.id}
+              item={child as TItem}
+              selectedIds={selectedIds}
+              onToggle={onToggle}
+              renderMeta={renderMeta}
+            />
+          ))}
+        </ul>
+      ) : null}
+    </li>
+  );
+}
+
+export function CheckboxTree<TItem extends TreeItem>({
+  items,
+  selectedIds,
+  onSelectedIdsChange,
+  renderMeta,
+  emptyMessage = 'No items available.',
+}: {
+  items: TItem[];
+  selectedIds: number[];
+  onSelectedIdsChange: (ids: number[]) => void;
+  renderMeta?: (item: TItem) => ReactNode;
+  emptyMessage?: string;
+}) {
+  const selectedSet = useMemo(() => new Set(selectedIds), [selectedIds]);
+
+  const handleToggle = (item: TItem, checked: boolean) => {
+    const next = new Set(selectedSet);
+    collectTreeItemIds(item).forEach((id) => {
+      if (checked) {
+        next.add(id);
+      } else {
+        next.delete(id);
+      }
+    });
+    onSelectedIdsChange(Array.from(next));
+  };
+
+  if (items.length === 0) {
+    return (
+      <div className="rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground">
+        {emptyMessage}
+      </div>
+    );
+  }
+
+  return (
+    <ul className="space-y-2">
+      {items.map((item) => (
+        <CheckboxTreeNode
+          key={item.id}
+          item={item}
+          selectedIds={selectedSet}
+          onToggle={handleToggle}
+          renderMeta={renderMeta}
+        />
+      ))}
+    </ul>
+  );
+}

src/hooks/useDebounce.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export function useDebounce<TValue>(value: TValue, delayMs = 400): TValue {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+
+    return () => window.clearTimeout(timer);
+  }, [delayMs, value]);
+
+  return debouncedValue;
+}