kasy-cli 1.37.1 → 1.39.0

package/templates/firebase/lib/features/settings/ui/components/admin/admin_users_tab.dart

@@ -3,8 +3,14 @@ import 'dart:math';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/components/kasy_avatar.dart';
+import 'package:kasy_kit/components/kasy_button.dart';
+import 'package:kasy_kit/components/kasy_card.dart';
+import 'package:kasy_kit/components/kasy_drop_down.dart';
+import 'package:kasy_kit/components/kasy_skeleton.dart';
 import 'package:kasy_kit/components/kasy_status_tag.dart';
+import 'package:kasy_kit/components/kasy_text_field.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_hover.dart';
 import 'package:kasy_kit/features/settings/ui/components/admin/admin_users_api.dart';
 import 'package:kasy_kit/i18n/translations.g.dart';
 
@@ -120,50 +126,90 @@ class _AdminUsersTabState extends ConsumerState<AdminUsersTab> {
     final async = ref.watch(_usersResultProvider);
 
     return _HCenter(
-      child: async.when(
-        loading: () => const _LoadingState(),
-        error: (e, _) => _ErrorState(onRetry: _refresh),
-        data: (result) {
-          final processed = _process(result.users);
-          final total = processed.length;
-          final pageCount = max(1, (total / _pageSize).ceil());
-          final page = _page.clamp(0, pageCount - 1);
-          final start = page * _pageSize;
-          final end = min(start + _pageSize, total);
-          final visible = processed.sublist(start, end);
-
-          return Column(
-            crossAxisAlignment: CrossAxisAlignment.stretch,
-            children: [
-              _Toolbar(
-                controller: _searchCtrl,
-                resultCount: total,
-                subscribersOnly: _subscribersOnly,
-                onSearch: _onSearch,
-                onSubscribersOnly: _setSubscribersOnly,
-                onRefresh: _refresh,
-              ),
-              if (result.truncated)
-                _TruncatedNote(count: result.users.length),
-              _TableHeader(
-                sortCol: _sortCol,
-                asc: _asc,
-                onSort: _onSort,
+      child: LayoutBuilder(
+        builder: (context, constraints) {
+          // Mobile: a horizontal table is cramped, so each user becomes a
+          // vertical card. Tablet/desktop keep the denser table.
+          final bool cards = constraints.maxWidth < 560;
+          final Widget content = async.when(
+            // Show the skeleton on a manual refresh too, so tapping Refresh
+            // gives clear feedback even when nothing actually changed.
+            skipLoadingOnRefresh: false,
+            loading: () => _LoadingState(cards: cards),
+            error: (e, _) => _ErrorState(onRetry: _refresh),
+            data: (result) {
+              final processed = _process(result.users);
+              final total = processed.length;
+              final pageCount = max(1, (total / _pageSize).ceil());
+              final page = _page.clamp(0, pageCount - 1);
+              final start = page * _pageSize;
+              final end = min(start + _pageSize, total);
+              final visible = processed.sublist(start, end);
+
+              return Column(
+                crossAxisAlignment: CrossAxisAlignment.stretch,
+                children: [
+                  _Toolbar(
+                    controller: _searchCtrl,
+                    resultCount: total,
+                    subscribersOnly: _subscribersOnly,
+                    onSearch: _onSearch,
+                    onSubscribersOnly: _setSubscribersOnly,
+                    onRefresh: _refresh,
+                  ),
+                  if (result.truncated)
+                    _TruncatedNote(count: result.users.length),
+                  // Column headers only make sense for the table layout.
+                  if (!cards)
+                    _TableHeader(sortCol: _sortCol, asc: _asc, onSort: _onSort)
+                  else
+                    const SizedBox(height: KasySpacing.md),
+                  Expanded(
+                    child: visible.isEmpty
+                        ? _EmptyState(searching: _search.trim().isNotEmpty)
+                        : _TableBody(
+                            users: visible,
+                            cards: cards,
+                            rangeFrom: start + 1,
+                            rangeTo: end,
+                            total: total,
+                            page: page,
+                            pageCount: pageCount,
+                            onPage: (p) => setState(() => _page = p),
+                          ),
+                  ),
+                ],
+              );
+            },
+          );
+
+          // Mobile keeps the borderless cards (they carry their own surface).
+          // Tablet/desktop wrap the whole table in a surface panel so it reads
+          // as a deliberate card, not loose rows on the page background.
+          if (cards) return content;
+          return Padding(
+            padding: const EdgeInsets.fromLTRB(
+              KasySpacing.pageHorizontalGutter,
+              KasySpacing.belowChromeContentGap,
+              KasySpacing.pageHorizontalGutter,
+              KasySpacing.md,
+            ),
+            child: DecoratedBox(
+              decoration: BoxDecoration(
+                color: context.colors.surface,
+                borderRadius: BorderRadius.circular(18),
+                border: Border.all(
+                  color: context.colors.outline.withValues(
+                    alpha: context.isDark ? 0.45 : 0.6,
+                  ),
+                ),
+                boxShadow: [KasyShadows.component(context)],
               ),
-              Expanded(
-                child: visible.isEmpty
-                    ? _EmptyState(searching: _search.trim().isNotEmpty)
-                    : _TableBody(
-                        users: visible,
-                        rangeFrom: start + 1,
-                        rangeTo: end,
-                        total: total,
-                        page: page,
-                        pageCount: pageCount,
-                        onPage: (p) => setState(() => _page = p),
-                      ),
+              child: ClipRRect(
+                borderRadius: BorderRadius.circular(18),
+                child: content,
               ),
-            ],
+            ),
           );
         },
       ),
@@ -354,89 +400,20 @@ class _FilterButton extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final u = t.admin_console.users;
-    final active = subscribersOnly;
-    final accent = active ? context.colors.primary : context.colors.onSurface;
-
-    return PopupMenuButton<bool>(
-      initialValue: subscribersOnly,
-      onSelected: onChanged,
-      tooltip: '', // never a "show menu" tooltip — the label already explains it
-      position: PopupMenuPosition.under,
-      constraints: const BoxConstraints(
-        minWidth: _filterWidth,
-        maxWidth: _filterWidth,
-      ),
-      color: context.colors.surface,
-      elevation: 6,
-      shadowColor: Colors.black.withValues(alpha: 0.12),
-      shape: RoundedRectangleBorder(
-        borderRadius: BorderRadius.circular(KasyRadius.md),
-        side: BorderSide(color: context.colors.outline.withValues(alpha: 0.5)),
-      ),
-      itemBuilder: (_) => [
-        _filterItem(context, value: false, label: u.filter_all, selected: !active),
-        _filterItem(context, value: true, label: u.filter_subscribers, selected: active),
-      ],
-      child: Container(
-        width: _filterWidth,
-        height: 38,
-        padding: const EdgeInsets.symmetric(horizontal: 12),
-        decoration: BoxDecoration(
-          color: active
-              ? context.colors.primary.withValues(alpha: 0.10)
-              : context.colors.surface,
-          borderRadius: BorderRadius.circular(KasyRadius.sm),
-          border: Border.all(
-            color: active
-                ? context.colors.primary.withValues(alpha: 0.45)
-                : context.colors.outline.withValues(alpha: 0.5),
-          ),
-        ),
-        child: Row(
-          children: [
-            Icon(Icons.tune_rounded, size: 16, color: accent),
-            const SizedBox(width: 8),
-            Expanded(
-              child: Text(
-                active ? u.filter_subscribers : u.filter_all,
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-                style: context.textTheme.bodySmall?.copyWith(
-                  color: accent,
-                  fontWeight: FontWeight.w600,
-                ),
-              ),
-            ),
-            Icon(Icons.keyboard_arrow_down_rounded, size: 18, color: accent),
-          ],
-        ),
-      ),
-    );
-  }
-
-  PopupMenuItem<bool> _filterItem(
-    BuildContext context, {
-    required bool value,
-    required String label,
-    required bool selected,
-  }) {
-    return PopupMenuItem<bool>(
-      value: value,
-      height: 42,
-      child: Row(
-        children: [
-          Expanded(
-            child: Text(
-              label,
-              style: context.textTheme.bodyMedium?.copyWith(
-                color: context.colors.onSurface,
-                fontWeight: selected ? FontWeight.w600 : FontWeight.w400,
-              ),
-            ),
-          ),
-          if (selected)
-            Icon(Icons.check_rounded, size: 16, color: context.colors.primary),
+    // Kit dropdown: the floating panel lives under the app Overlay so it always
+    // follows the real light/dark theme (the old PopupMenuButton rendered the
+    // menu light even in dark mode).
+    return SizedBox(
+      width: _filterWidth,
+      child: KasyDropDown<bool>(
+        value: subscribersOnly,
+        leadingIcon: Icons.tune_rounded,
+        variant: KasyTextFieldVariant.flat,
+        items: [
+          KasyDropDownItem(value: false, label: u.filter_all),
+          KasyDropDownItem(value: true, label: u.filter_subscribers),
         ],
+        onChanged: onChanged,
       ),
     );
   }
@@ -455,23 +432,18 @@ class _IconAction extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     // Icon-only control: a tooltip is the right call here (no visible label).
+    // KasyButton.iconOnly gives the kit's outlined icon button with proper web
+    // hover, focus ring and cursor (no Material ripple).
     return Tooltip(
       message: tooltip,
-      child: InkWell(
-        onTap: onTap,
-        borderRadius: BorderRadius.circular(KasyRadius.sm),
-        child: Container(
-          width: 38,
-          height: 38,
-          decoration: BoxDecoration(
-            color: context.colors.surface,
-            borderRadius: BorderRadius.circular(KasyRadius.sm),
-            border: Border.all(
-              color: context.colors.outline.withValues(alpha: 0.5),
-            ),
-          ),
-          child: Icon(icon, size: 18, color: context.colors.onSurface),
-        ),
+      child: KasyButton.iconOnly(
+        icon: icon,
+        variant: KasyButtonVariant.outline,
+        size: KasyButtonSize.small,
+        iconOnlyLayoutExtent: 38,
+        iconGlyphSize: 18,
+        onPressed: onTap,
+        semanticLabel: tooltip,
       ),
     );
   }
@@ -533,9 +505,9 @@ class _TableHeader extends StatelessWidget {
           bottom:
               BorderSide(color: context.colors.outline.withValues(alpha: 0.3)),
         ),
-        color: context.isDark
-            ? context.colors.surface.withValues(alpha: 0.5)
-            : context.colors.surfaceNeutralSoft.withValues(alpha: 0.4),
+        // Design-system neutral surface (solid) so the header band reads as a
+        // distinct table head instead of blending into the white panel.
+        color: context.colors.surfaceNeutralSoft,
       ),
       padding: const EdgeInsets.symmetric(
         horizontal: KasySpacing.pageHorizontalGutter,
@@ -600,8 +572,9 @@ class _HeaderCell extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final color = active ? context.colors.onSurface : context.colors.muted;
-    return InkWell(
+    return KasyHover(
       onTap: onTap,
+      focusable: true,
       borderRadius: BorderRadius.circular(KasyRadius.xs),
       child: Padding(
         padding: const EdgeInsets.symmetric(vertical: 6),
@@ -640,6 +613,7 @@ class _HeaderCell extends StatelessWidget {
 
 class _TableBody extends StatelessWidget {
   final List<AdminUser> users;
+  final bool cards;
   final int rangeFrom;
   final int rangeTo;
   final int total;
@@ -649,6 +623,7 @@ class _TableBody extends StatelessWidget {
 
   const _TableBody({
     required this.users,
+    required this.cards,
     required this.rangeFrom,
     required this.rangeTo,
     required this.total,
@@ -663,49 +638,77 @@ class _TableBody extends StatelessWidget {
     return Column(
       children: [
         Expanded(
-          child: ListView.separated(
-            // Scrolling the results means the user stopped typing in the search
-            // field above, so dismiss the keyboard to show more of the list.
-            keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag,
-            padding: const EdgeInsets.only(bottom: KasySpacing.xs),
-            itemCount: users.length,
-            separatorBuilder: (_, _) => Divider(
-              height: 1,
-              thickness: 1,
-              indent: KasySpacing.pageHorizontalGutter,
-              endIndent: KasySpacing.pageHorizontalGutter,
-              color: context.colors.outline.withValues(alpha: 0.18),
+          // Soft fade at the bottom edge so rows/cards dissolve into the pager
+          // instead of being sliced by a hard line — reads far cleaner when the
+          // last item is mid-scroll behind the pinned footer.
+          child: ShaderMask(
+            shaderCallback: (rect) => const LinearGradient(
+              begin: Alignment.bottomCenter,
+              end: Alignment.topCenter,
+              colors: [Colors.transparent, Colors.black],
+              stops: [0.0, 0.045],
+            ).createShader(rect),
+            blendMode: BlendMode.dstIn,
+            child: ListView.separated(
+              // Scrolling the results means the user stopped typing in the
+              // search field above, so dismiss the keyboard to show more rows.
+              keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag,
+              padding: cards
+                  ? const EdgeInsets.fromLTRB(
+                      KasySpacing.pageHorizontalGutter,
+                      0,
+                      KasySpacing.pageHorizontalGutter,
+                      KasySpacing.lg,
+                    )
+                  : const EdgeInsets.only(bottom: KasySpacing.md),
+              itemCount: users.length,
+              separatorBuilder: cards
+                  ? (_, _) => const SizedBox(height: KasySpacing.sm)
+                  : (_, _) => Divider(
+                        height: 1,
+                        thickness: 1,
+                        indent: KasySpacing.pageHorizontalGutter,
+                        endIndent: KasySpacing.pageHorizontalGutter,
+                        color: context.colors.outline.withValues(alpha: 0.18),
+                      ),
+              itemBuilder: (_, i) =>
+                  cards ? _UserCard(user: users[i]) : _UserRow(user: users[i]),
             ),
-            itemBuilder: (_, i) => _UserRow(user: users[i]),
           ),
         ),
         Container(
           decoration: BoxDecoration(
             border: Border(
               top: BorderSide(
-                color: context.colors.outline.withValues(alpha: 0.3),
+                color: context.colors.outline.withValues(alpha: 0.15),
               ),
             ),
           ),
           padding: EdgeInsets.fromLTRB(
             KasySpacing.pageHorizontalGutter,
-            KasySpacing.smd,
+            KasySpacing.md,
             KasySpacing.pageHorizontalGutter,
             MediaQuery.paddingOf(context).bottom + KasySpacing.xl,
           ),
           child: LayoutBuilder(
             builder: (context, c) {
-              final pager = _Pagination(
-                page: page,
-                pageCount: pageCount,
-                onPage: onPage,
-              );
               final label = Text(
                 u.results(from: rangeFrom, to: rangeTo, total: total),
                 style: context.textTheme.bodySmall?.copyWith(
                   color: context.colors.muted,
                 ),
               );
+              // A single page has no "previous/next" to offer — showing the
+              // disabled controls is just dead weight. Keep only the quiet
+              // count, centered, so the bar stays clean (pro dashboard style).
+              if (pageCount <= 1) {
+                return Center(child: label);
+              }
+              final pager = _Pagination(
+                page: page,
+                pageCount: pageCount,
+                onPage: onPage,
+              );
               if (c.maxWidth < 460) {
                 return Column(
                   children: [
@@ -802,32 +805,38 @@ class _PageNum extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return InkWell(
-      onTap: selected ? null : onTap,
-      borderRadius: BorderRadius.circular(KasyRadius.sm),
-      child: Container(
-        constraints: const BoxConstraints(minWidth: 32),
-        height: 32,
-        alignment: Alignment.center,
-        padding: const EdgeInsets.symmetric(horizontal: 6),
-        decoration: BoxDecoration(
-          color: selected ? context.colors.primary : context.colors.surface,
-          borderRadius: BorderRadius.circular(KasyRadius.sm),
-          border: Border.all(
-            color: selected
-                ? context.colors.primary
-                : context.colors.outline.withValues(alpha: 0.5),
-          ),
+    final Widget content = Container(
+      constraints: const BoxConstraints(minWidth: 32),
+      height: 32,
+      alignment: Alignment.center,
+      padding: const EdgeInsets.symmetric(horizontal: 6),
+      decoration: BoxDecoration(
+        // Unselected pages stay transparent (border only) so KasyHover's overlay
+        // shows through on web hover; the current page keeps the solid primary.
+        color: selected ? context.colors.primary : Colors.transparent,
+        borderRadius: BorderRadius.circular(KasyRadius.sm),
+        border: Border.all(
+          color: selected
+              ? context.colors.primary
+              : context.colors.outline.withValues(alpha: 0.5),
         ),
-        child: Text(
-          '$number',
-          style: context.textTheme.labelMedium?.copyWith(
-            color: selected ? context.colors.onPrimary : context.colors.onSurface,
-            fontWeight: FontWeight.w700,
-          ),
+      ),
+      child: Text(
+        '$number',
+        style: context.textTheme.labelMedium?.copyWith(
+          color: selected ? context.colors.onPrimary : context.colors.onSurface,
+          fontWeight: FontWeight.w700,
         ),
       ),
     );
+    // Current page: not tappable, no hover. Other pages get the kit hover.
+    if (selected) return content;
+    return KasyHover(
+      onTap: onTap,
+      focusable: true,
+      borderRadius: BorderRadius.circular(KasyRadius.sm),
+      child: content,
+    );
   }
 }
 
@@ -877,23 +886,27 @@ class _NavBtn extends StatelessWidget {
       ),
     );
     final ic = Icon(icon, size: 18, color: color);
-    return InkWell(
-      onTap: enabled ? onTap : null,
-      borderRadius: BorderRadius.circular(KasyRadius.sm),
-      child: Container(
-        height: 32,
-        padding: const EdgeInsets.symmetric(horizontal: 8),
-        decoration: BoxDecoration(
-          borderRadius: BorderRadius.circular(KasyRadius.sm),
-          border: Border.all(
-            color: context.colors.outline.withValues(alpha: enabled ? 0.5 : 0.25),
-          ),
-        ),
-        child: Row(
-          mainAxisSize: MainAxisSize.min,
-          children: leading ? [ic, const SizedBox(width: 2), text] : [text, const SizedBox(width: 2), ic],
+    final Widget content = Container(
+      height: 32,
+      padding: const EdgeInsets.symmetric(horizontal: 8),
+      decoration: BoxDecoration(
+        borderRadius: BorderRadius.circular(KasyRadius.sm),
+        border: Border.all(
+          color: context.colors.outline.withValues(alpha: enabled ? 0.5 : 0.25),
         ),
       ),
+      child: Row(
+        mainAxisSize: MainAxisSize.min,
+        children: leading ? [ic, const SizedBox(width: 2), text] : [text, const SizedBox(width: 2), ic],
+      ),
+    );
+    // Disabled (prev/next at the list edges): no hover, cursor or tap.
+    if (!enabled) return content;
+    return KasyHover(
+      onTap: onTap,
+      focusable: true,
+      borderRadius: BorderRadius.circular(KasyRadius.sm),
+      child: content,
     );
   }
 }
@@ -943,6 +956,7 @@ class _UserRow extends StatelessWidget {
               children: [
                 KasyAvatar(
                   diameter: 34,
+                  image: _avatarImage(user),
                   initials: hasName ? user.name : (hasEmail ? user.email : null),
                   tone: _avatarTone(
                     hasName ? user.name : (hasEmail ? user.email : null),
@@ -1014,7 +1028,7 @@ class _UserRow extends StatelessWidget {
           SizedBox(
             width: 88,
             child: Text(
-              user.createdAt != null ? _formatDate(user.createdAt!) : '—',
+              user.createdAt != null ? _formatJoined(user.createdAt!) : '—',
               style: context.textTheme.bodySmall?.copyWith(
                 color: context.colors.muted,
               ),
@@ -1025,14 +1039,128 @@ class _UserRow extends StatelessWidget {
     );
   }
 
-  String _formatDate(DateTime dt) {
-    final d = dt.toLocal();
-    return '${d.day.toString().padLeft(2, '0')}/'
-        '${d.month.toString().padLeft(2, '0')}/'
-        '${d.year.toString().substring(2)}';
+}
+
+/// Mobile card for a single user — the same data as a table row, stacked
+/// vertically so it reads comfortably on a narrow screen.
+class _UserCard extends StatelessWidget {
+  final AdminUser user;
+  const _UserCard({required this.user});
+
+  @override
+  Widget build(BuildContext context) {
+    final u = t.admin_console.users;
+    final bool hasName = user.name?.isNotEmpty == true;
+    final bool hasEmail = user.email?.isNotEmpty == true;
+    final String primaryText =
+        hasName ? user.name! : (hasEmail ? user.email! : u.anonymous);
+    final String? subText = hasName && hasEmail ? user.email : null;
+    final bool isAnonymous = !hasName && !hasEmail;
+
+    return KasyCard(
+      // Default elevated (white surface + shadow over the F5F5F5 page) so the
+      // card reads as a real card, not a transparent outline that blends into
+      // the screen.
+      padding: const EdgeInsets.all(KasySpacing.md),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          Row(
+            children: [
+              KasyAvatar(
+                diameter: 38,
+                image: _avatarImage(user),
+                initials: hasName ? user.name : (hasEmail ? user.email : null),
+                tone: _avatarTone(
+                  hasName ? user.name : (hasEmail ? user.email : null),
+                ),
+              ),
+              const SizedBox(width: KasySpacing.sm),
+              Expanded(
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    Text(
+                      primaryText,
+                      maxLines: 1,
+                      overflow: TextOverflow.ellipsis,
+                      style: isAnonymous
+                          ? context.textTheme.bodyMedium?.copyWith(
+                              color: context.colors.muted,
+                              fontStyle: FontStyle.italic,
+                            )
+                          : context.kasyTextTheme.rowTitle.copyWith(
+                              color: context.colors.onSurface,
+                            ),
+                    ),
+                    if (subText != null) ...[
+                      const SizedBox(height: 1),
+                      Text(
+                        subText,
+                        maxLines: 1,
+                        overflow: TextOverflow.ellipsis,
+                        style: context.textTheme.bodySmall?.copyWith(
+                          color: context.colors.muted,
+                        ),
+                      ),
+                    ],
+                  ],
+                ),
+              ),
+            ],
+          ),
+          const SizedBox(height: KasySpacing.smd),
+          Divider(
+            height: 1,
+            color: context.colors.outline.withValues(alpha: 0.25),
+          ),
+          const SizedBox(height: KasySpacing.smd),
+          Row(
+            children: [
+              Expanded(
+                child: Wrap(
+                  spacing: KasySpacing.xs,
+                  runSpacing: KasySpacing.xs,
+                  children: [
+                    KasyStatusTag(
+                      label: hasEmail ? u.status_active : u.status_inactive,
+                      tone: hasEmail
+                          ? KasyStatusTagTone.success
+                          : KasyStatusTagTone.neutral,
+                    ),
+                    KasyStatusTag(
+                      label: user.subscriber ? u.plan_subscriber : u.plan_free,
+                      tone: user.subscriber
+                          ? KasyStatusTagTone.primary
+                          : KasyStatusTagTone.neutral,
+                    ),
+                  ],
+                ),
+              ),
+              const SizedBox(width: KasySpacing.sm),
+              Text(
+                user.createdAt != null ? _formatJoined(user.createdAt!) : '—',
+                style: context.textTheme.bodySmall?.copyWith(
+                  color: context.colors.muted,
+                ),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
   }
 }
 
+/// Shared joined-date formatter (dd/MM/yy) for the table row and mobile card.
+String _formatJoined(DateTime dt) {
+  final d = dt.toLocal();
+  return '${d.day.toString().padLeft(2, '0')}/'
+      '${d.month.toString().padLeft(2, '0')}/'
+      '${d.year.toString().substring(2)}';
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Avatar tone — a stable design-system tone per user (variety, not random).
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1049,6 +1177,14 @@ KasyAvatarTone _avatarTone(String? seed) {
   return tones[seed.trimLeft().codeUnitAt(0) % tones.length];
 }
 
+/// The user's photo when they have one, else null so [KasyAvatar] falls back to
+/// initials. The avatarPath is the public URL the backend already stores.
+ImageProvider? _avatarImage(AdminUser user) {
+  final path = user.avatarPath;
+  if (path == null || path.isEmpty) return null;
+  return NetworkImage(path);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Loading / empty / error states (big icon over text)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1123,18 +1259,109 @@ class _IconBubble extends StatelessWidget {
   }
 }
 
+/// Skeleton placeholder that mirrors the real layout (table rows on wide
+/// viewports, cards on mobile) so loading reads as the product, not a spinner.
 class _LoadingState extends StatelessWidget {
-  const _LoadingState();
+  final bool cards;
+  const _LoadingState({required this.cards});
 
   @override
   Widget build(BuildContext context) {
-    return _CenteredState(
-      icon: const SizedBox(
-        width: 40,
-        height: 40,
-        child: CircularProgressIndicator.adaptive(strokeWidth: 2.5),
+    final int count = cards ? 5 : 7;
+    return KasySkeletonGroup(
+      child: SingleChildScrollView(
+        physics: const NeverScrollableScrollPhysics(),
+        padding: const EdgeInsets.fromLTRB(
+          KasySpacing.pageHorizontalGutter,
+          KasySpacing.lg,
+          KasySpacing.pageHorizontalGutter,
+          0,
+        ),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            for (int i = 0; i < count; i++) ...[
+              if (cards)
+                const _UserCardSkeleton()
+              else
+                const _UserRowSkeleton(),
+              SizedBox(height: cards ? KasySpacing.sm : KasySpacing.md),
+            ],
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _UserRowSkeleton extends StatelessWidget {
+  const _UserRowSkeleton();
+
+  @override
+  Widget build(BuildContext context) {
+    return const Row(
+      children: [
+        KasySkeleton.circle(size: 34),
+        SizedBox(width: 10),
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              KasySkeleton(width: 140, height: 12),
+              SizedBox(height: 6),
+              KasySkeleton(width: 90, height: 10),
+            ],
+          ),
+        ),
+        SizedBox(width: 12),
+        KasySkeleton(width: 56, height: 20),
+        SizedBox(width: 12),
+        KasySkeleton(width: 40, height: 12),
+      ],
+    );
+  }
+}
+
+class _UserCardSkeleton extends StatelessWidget {
+  const _UserCardSkeleton();
+
+  @override
+  Widget build(BuildContext context) {
+    return const KasyCard(
+      padding: EdgeInsets.all(KasySpacing.md),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          Row(
+            children: [
+              KasySkeleton.circle(size: 38),
+              SizedBox(width: KasySpacing.sm),
+              Expanded(
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    KasySkeleton(width: 150, height: 13),
+                    SizedBox(height: 6),
+                    KasySkeleton(width: 100, height: 10),
+                  ],
+                ),
+              ),
+            ],
+          ),
+          SizedBox(height: KasySpacing.md),
+          Row(
+            children: [
+              KasySkeleton(width: 64, height: 22),
+              SizedBox(width: 8),
+              KasySkeleton(width: 64, height: 22),
+              Spacer(),
+              KasySkeleton(width: 44, height: 12),
+            ],
+          ),
+        ],
       ),
-      title: t.admin_console.users.loading,
     );
   }
 }
@@ -1167,26 +1394,11 @@ class _ErrorState extends StatelessWidget {
       icon: const _IconBubble(Icons.error_outline_rounded),
       title: u.title,
       subtitle: u.error,
-      action: InkWell(
-        onTap: onRetry,
-        borderRadius: BorderRadius.circular(KasyRadius.sm),
-        child: Container(
-          padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
-          decoration: BoxDecoration(
-            color: context.colors.surface,
-            borderRadius: BorderRadius.circular(KasyRadius.sm),
-            border: Border.all(
-              color: context.colors.outline.withValues(alpha: 0.5),
-            ),
-          ),
-          child: Text(
-            u.retry,
-            style: context.textTheme.labelMedium?.copyWith(
-              color: context.colors.onSurface,
-              fontWeight: FontWeight.w600,
-            ),
-          ),
-        ),
+      action: KasyButton(
+        label: u.retry,
+        variant: KasyButtonVariant.outline,
+        size: KasyButtonSize.small,
+        onPressed: onRetry,
       ),
     );
   }