@podosoft/podokit 0.13.0 → 0.15.0

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/account-page.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { goto } from "$app/navigation";
+  import { goto, invalidateAll } from "$app/navigation";
   import QRCode from "qrcode";
   import { Button } from "$lib/components/ui/button";
   import { Input } from "$lib/components/ui/input";
@@ -14,7 +14,17 @@
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
   import { untrack } from "svelte";
   import type { SessionUser } from "../../app.d.ts";
-  import type { Capabilities } from "@podosoft/podokit-api-client";
+  import UserAvatar from "./user-avatar.svelte";
+  import {
+    ApiError,
+    PROFILE_IMAGE_DIMENSIONS_INVALID,
+    PROFILE_IMAGE_POLICY,
+    PROFILE_IMAGE_REQUIRED,
+    PROFILE_IMAGE_TOO_LARGE,
+    PROFILE_IMAGE_TYPE_INVALID,
+    type Capabilities,
+    type ProfileImageResponse,
+  } from "@podosoft/podokit-api-client";
 
   let {
     data,
@@ -45,6 +55,15 @@
   let name = $state(untrack(() => data.user.name));
   let username = $state(untrack(() => data.user.username ?? ""));
   let savingProfile = $state(false);
+  let profileImage = $state<string | null>(untrack(() => data.user.image ?? null));
+  let profileImageInput = $state<HTMLInputElement | null>(null);
+  let profileImageBusy = $state(false);
+  const profileImageAccept = PROFILE_IMAGE_POLICY.mimeTypes.join(",");
+  const profileImageHint = fmt(i18n.t.account.profileImageHint, {
+    size: PROFILE_IMAGE_POLICY.maxBytes / 1024 / 1024,
+    width: PROFILE_IMAGE_POLICY.maxWidth,
+    height: PROFILE_IMAGE_POLICY.maxHeight,
+  });
   const nameChanged = $derived(
     (name.trim() !== "" && name !== data.user.name) || (caps.username && username !== (data.user.username ?? "")),
   );
@@ -60,6 +79,93 @@
     else toast.success(i18n.t.account.saved);
   }
 
+  function profileImageErrorMessage(code: string): string {
+    switch (code) {
+      case PROFILE_IMAGE_REQUIRED:
+        return i18n.t.account.profileImageRequired;
+      case PROFILE_IMAGE_TOO_LARGE:
+        return i18n.t.account.profileImageTooLarge;
+      case PROFILE_IMAGE_DIMENSIONS_INVALID:
+        return i18n.t.account.profileImageDimensionsInvalid;
+      case PROFILE_IMAGE_TYPE_INVALID:
+        return i18n.t.account.profileImageTypeInvalid;
+      default:
+        return i18n.t.account.profileImageFailed;
+    }
+  }
+
+  function imageDimensions(file: File): Promise<{ width: number; height: number }> {
+    return new Promise((resolve, reject) => {
+      const url = URL.createObjectURL(file);
+      const image = new Image();
+      image.onload = () => {
+        URL.revokeObjectURL(url);
+        resolve({ width: image.naturalWidth, height: image.naturalHeight });
+      };
+      image.onerror = () => {
+        URL.revokeObjectURL(url);
+        reject(new Error("Invalid image"));
+      };
+      image.src = url;
+    });
+  }
+
+  async function validateProfileImageSelection(file: File): Promise<string | null> {
+    if (!(PROFILE_IMAGE_POLICY.mimeTypes as readonly string[]).includes(file.type)) {
+      return PROFILE_IMAGE_TYPE_INVALID;
+    }
+    if (file.size > PROFILE_IMAGE_POLICY.maxBytes) return PROFILE_IMAGE_TOO_LARGE;
+    try {
+      const dimensions = await imageDimensions(file);
+      if (
+        dimensions.width > PROFILE_IMAGE_POLICY.maxWidth
+        || dimensions.height > PROFILE_IMAGE_POLICY.maxHeight
+      ) {
+        return PROFILE_IMAGE_DIMENSIONS_INVALID;
+      }
+    } catch {
+      return PROFILE_IMAGE_TYPE_INVALID;
+    }
+    return null;
+  }
+
+  async function uploadProfileImage(event: Event): Promise<void> {
+    const input = event.currentTarget as HTMLInputElement;
+    const file = input.files?.[0];
+    input.value = "";
+    if (!file) return;
+    const validationCode = await validateProfileImageSelection(file);
+    if (validationCode) return void toast.error(profileImageErrorMessage(validationCode));
+
+    profileImageBusy = true;
+    try {
+      const form = new FormData();
+      form.set("file", file, file.name);
+      const response = await api.postForm<ProfileImageResponse>("/account/profile-image", form);
+      profileImage = response.image;
+      toast.success(i18n.t.account.profileImageUpdated);
+      await invalidateAll();
+    } catch (error: unknown) {
+      toast.error(profileImageErrorMessage(error instanceof ApiError ? error.code : ""));
+    } finally {
+      profileImageBusy = false;
+    }
+  }
+
+  async function removeProfileImage(): Promise<void> {
+    profileImageBusy = true;
+    try {
+      const response = await api.del<ProfileImageResponse>("/account/profile-image");
+      profileImage = response.image;
+      toast.success(i18n.t.account.profileImageRemoved);
+      await invalidateAll();
+    } catch (error: unknown) {
+      toast.error(profileImageErrorMessage(error instanceof ApiError ? error.code : ""));
+    } finally {
+      profileImageBusy = false;
+    }
+  }
+
   // Phone number — register + verify with an SMS code (dev delivery is a stub).
   let phone = $state(untrack(() => data.user.phoneNumber ?? ""));
   let phoneCode = $state("");
@@ -404,6 +510,53 @@
         <Card.Root>
           <Card.Header><Card.Title>{i18n.t.account.profile}</Card.Title></Card.Header>
           <Card.Content>
+            <div class="mb-6 flex max-w-md items-center gap-4 border-b pb-6">
+              <div data-testid="profile-image-preview">
+                <UserAvatar user={{ ...data.user, image: profileImage }} class="size-20 shrink-0" />
+              </div>
+              <div class="min-w-0 flex-1 space-y-2">
+                <Label for="profile-image">{i18n.t.account.profileImage}</Label>
+                <p id="profile-image-hint" class="text-muted-foreground text-xs" data-testid="profile-image-hint">
+                  {profileImageHint}
+                </p>
+                <Input
+                  id="profile-image"
+                  type="file"
+                  accept={profileImageAccept}
+                  class="sr-only"
+                  aria-describedby="profile-image-hint"
+                  disabled={profileImageBusy}
+                  bind:ref={profileImageInput}
+                  onchange={uploadProfileImage}
+                />
+                <div class="flex flex-wrap gap-2">
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    disabled={profileImageBusy}
+                    onclick={() => profileImageInput?.click()}
+                  >
+                    {profileImageBusy
+                      ? i18n.t.account.profileImageUploading
+                      : profileImage
+                        ? i18n.t.account.profileImageReplace
+                        : i18n.t.account.profileImageUpload}
+                  </Button>
+                  {#if profileImage}
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      disabled={profileImageBusy}
+                      onclick={removeProfileImage}
+                    >
+                      {i18n.t.account.profileImageRemove}
+                    </Button>
+                  {/if}
+                </div>
+              </div>
+            </div>
             <form class="flex max-w-md flex-col gap-4" onsubmit={saveProfile}>
               <div class="flex flex-col gap-2">
                 <Label for="name">{i18n.t.account.name}</Label>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/data-table.svelte

@@ -1,14 +1,34 @@
 <script lang="ts" module>
+  import { cn } from "$lib/utils";
+
+  export type DataTableBreakpoint = "sm" | "md" | "lg" | "xl";
   export type DataTableColumn<Row> = {
     key: string;
     label: string;
     sortable?: boolean;
     class?: string;
+    hideBelow?: DataTableBreakpoint;
     // Value used for client-side sorting (defaults to row[key]). Use for nested
     // or derived fields, e.g. (s) => s.user.email.
     value?: (row: Row) => string | number | boolean | Date | null | undefined;
   };
   export type SortState = { key: string; dir: "asc" | "desc" };
+  export type DataTableRowContext = {
+    cellClass: (columnKey: string) => string | undefined;
+  };
+
+  const HIDE_BELOW_CLASS: Record<DataTableBreakpoint, string> = {
+    sm: "max-sm:hidden",
+    md: "max-md:hidden",
+    lg: "max-lg:hidden",
+    xl: "max-xl:hidden",
+  };
+
+  export function getDataTableColumnClass<Row>(
+    column: DataTableColumn<Row>,
+  ): string | undefined {
+    return cn(column.class, column.hideBelow ? HIDE_BELOW_CLASS[column.hideBelow] : undefined);
+  }
 
   // Shared page size for all admin tables — sized so a desktop viewport shows a
   // full list at a glance (rather than the old 5-row pages). Change it here to
@@ -33,9 +53,10 @@
   type Props = {
     columns: DataTableColumn<Row>[];
     rows: Row[];
-    row: Snippet<[Row]>; // renders the <Table.Cell>s for one row
+    row: Snippet<[Row, DataTableRowContext]>; // renders the <Table.Cell>s for one row
     getKey?: (row: Row, index: number) => string | number;
     empty?: string;
+    ariaLabel?: string;
     sort?: SortState | null;
     manualSort?: boolean;
     page?: number;
@@ -51,6 +72,7 @@
     row,
     getKey = (_r, i) => i,
     empty = "No data.",
+    ariaLabel,
     sort = $bindable(null),
     manualSort = false,
     page = $bindable(1),
@@ -71,6 +93,13 @@
     onChange?.({ sort, page });
   }
 
+  function cellClass(columnKey: string): string | undefined {
+    const column = columns.find((candidate) => candidate.key === columnKey);
+    return column ? getDataTableColumnClass(column) : undefined;
+  }
+
+  const rowContext: DataTableRowContext = { cellClass };
+
   function cmp(a: unknown, b: unknown): number {
     if (a == null && b == null) return 0;
     if (a == null) return -1;
@@ -95,12 +124,12 @@
 </script>
 
 <div class="rounded-md border">
-  <Table.Root>
+  <Table.Root aria-label={ariaLabel}>
     <Table.Header>
       <Table.Row>
         {#each columns as col (col.key)}
           <Table.Head
-            class={col.class}
+            class={getDataTableColumnClass(col)}
             aria-sort={sort?.key === col.key ? (sort.dir === "asc" ? "ascending" : "descending") : undefined}
           >
             {#if col.sortable}
@@ -121,7 +150,7 @@
     </Table.Header>
     <Table.Body>
       {#each view as r, i (getKey(r, i))}
-        <Table.Row>{@render row(r)}</Table.Row>
+        <Table.Row>{@render row(r, rowContext)}</Table.Row>
       {:else}
         <Table.Row>
           <Table.Cell colspan={columns.length} class="text-muted-foreground py-8 text-center">{empty}</Table.Cell>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/sidebar-user-menu.svelte

@@ -22,7 +22,7 @@
 <Sidebar.Menu>
   <Sidebar.MenuItem>
     <DropdownMenu.Root>
-      <DropdownMenu.Trigger>
+      <DropdownMenu.Trigger data-testid="sidebar-user-menu">
         {#snippet child({ props })}
           <Sidebar.MenuButton {...props} size="lg" class="data-[state=open]:bg-sidebar-accent">
             <UserAvatar {user} class="size-8" />

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/i18n/catalogs/admin-dashboard/en.json

@@ -502,6 +502,19 @@
   "account": {
     "title": "Account",
     "profile": "Profile",
+    "profileImage": "Profile image",
+    "profileImageHint": "PNG, JPEG, or WebP. Up to {size} MB and {width} × {height} px.",
+    "profileImageUpload": "Upload image",
+    "profileImageReplace": "Replace image",
+    "profileImageRemove": "Remove image",
+    "profileImageUploading": "Uploading…",
+    "profileImageUpdated": "Profile image updated",
+    "profileImageRemoved": "Profile image removed",
+    "profileImageRequired": "Choose an image to upload",
+    "profileImageTypeInvalid": "Choose a valid PNG, JPEG, or WebP image",
+    "profileImageTooLarge": "The image must be 2 MB or smaller",
+    "profileImageDimensionsInvalid": "The image must not exceed 2048 × 2048 px",
+    "profileImageFailed": "Failed to update profile image",
     "name": "Name",
     "username": "Username",
     "phone": "Phone number",

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/i18n/catalogs/admin-dashboard/ko.json

@@ -502,6 +502,19 @@
   "account": {
     "title": "계정",
     "profile": "프로필",
+    "profileImage": "프로필 이미지",
+    "profileImageHint": "PNG, JPEG, WebP · 최대 {size}MB · 최대 {width} × {height}px",
+    "profileImageUpload": "이미지 업로드",
+    "profileImageReplace": "이미지 교체",
+    "profileImageRemove": "이미지 제거",
+    "profileImageUploading": "업로드 중…",
+    "profileImageUpdated": "프로필 이미지를 변경했습니다",
+    "profileImageRemoved": "프로필 이미지를 제거했습니다",
+    "profileImageRequired": "업로드할 이미지를 선택해 주세요",
+    "profileImageTypeInvalid": "올바른 PNG, JPEG 또는 WebP 이미지를 선택해 주세요",
+    "profileImageTooLarge": "이미지는 2MB 이하여야 합니다",
+    "profileImageDimensionsInvalid": "이미지는 2048 × 2048px를 초과할 수 없습니다",
+    "profileImageFailed": "프로필 이미지 변경에 실패했습니다",
     "name": "이름",
     "username": "사용자명",
     "phone": "전화번호",

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/server/protected-layout.ts

@@ -0,0 +1,78 @@
+import { redirect } from "@sveltejs/kit";
+import type { Capabilities } from "@podosoft/podokit-api-client";
+import { requireBackendAvailable } from "./guards";
+
+type ServerFetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface ProtectedLayoutInput {
+  locals: App.Locals;
+  fetch: ServerFetch;
+}
+
+export interface ProtectedLayoutData {
+  user: App.Locals["user"];
+  impersonating: boolean;
+  capabilities: Capabilities;
+}
+
+/**
+ * Load the shared signed-in route context without imposing an application shell.
+ * The `(app)` group stays available for product UI, while `(admin)` adds admin chrome.
+ */
+export async function loadProtectedLayout({
+  locals,
+  fetch,
+}: ProtectedLayoutInput): Promise<ProtectedLayoutData> {
+  requireBackendAvailable(locals);
+
+  let capabilities: Capabilities = {
+    twoFactor: false,
+    providers: [],
+    deleteAccount: false,
+    auditLog: false,
+    emailVerification: false,
+    signupApprovalRequired: false,
+    passwordBreachCheck: false,
+    magicLink: false,
+    emailOtp: false,
+    username: false,
+    multiSession: false,
+    phoneNumber: false,
+    apiKey: false,
+    passkey: false,
+    organization: false,
+    oidcProvider: false,
+    roles: ["admin", "user"],
+  };
+  try {
+    const response = await fetch("/api/account/capabilities");
+    if (response.ok) capabilities = (await response.json()) as Capabilities;
+  } catch {
+    /* keep defaults */
+  }
+
+  // Require-two-factor policy: a signed-in user who has not enrolled is sent to
+  // setup. The API guard remains authoritative; this redirect provides the UX.
+  const user = locals.user as (App.Locals["user"] & { twoFactorEnabled?: boolean }) | null;
+  let mustEnrol = false;
+  if (user && !user.twoFactorEnabled) {
+    try {
+      const response = await fetch("/api/account/require-2fa");
+      mustEnrol =
+        response.ok &&
+        ((await response.json()) as { require2fa?: boolean }).require2fa === true;
+    } catch {
+      /* do not block the app if the policy check fails */
+    }
+  }
+  if (mustEnrol) redirect(302, "/setup-2fa");
+
+  return {
+    user: locals.user,
+    impersonating: Boolean(locals.session?.impersonatedBy),
+    capabilities,
+  };
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(admin)/+layout.server.ts

@@ -0,0 +1,8 @@
+import type { LayoutServerLoad } from "./$types";
+import { loadProtectedLayout } from "$lib/server/protected-layout";
+import { requireAdmin } from "$lib/server/guards";
+
+export const load: LayoutServerLoad = async ({ locals, fetch }) => {
+  requireAdmin(locals.user, locals);
+  return loadProtectedLayout({ locals, fetch });
+};

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/{(app) → (admin)}/+layout.svelte

@@ -3,7 +3,7 @@
   import * as Sidebar from "$lib/components/ui/sidebar";
   import { Separator } from "$lib/components/ui/separator";
   import { Button } from "$lib/components/ui/button";
-  import AppSidebar from "$lib/components/app-sidebar.svelte";
+  import AdminSidebar from "$lib/components/admin-sidebar.svelte";
   import ThemeToggle from "$lib/components/theme-toggle.svelte";
   import LanguageSwitch from "$lib/components/language-switch.svelte";
   import { Toaster } from "$lib/components/ui/sonner";
@@ -27,7 +27,7 @@
 </script>
 
 <Sidebar.Provider>
-  <AppSidebar user={data.user} capabilities={data.capabilities} />
+  <AdminSidebar user={data.user} capabilities={data.capabilities} />
   <Sidebar.Inset>
     {#if data.impersonating}
       <div class="bg-primary text-primary-foreground flex items-center justify-between gap-2 px-4 py-2 text-sm">

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/{(app) → (admin)}/admin/users/+page.svelte

@@ -16,6 +16,7 @@
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
+  import { cn } from "$lib/utils";
   import type { PageData } from "./$types";
 
   let { data }: { data: PageData } = $props();
@@ -58,9 +59,15 @@
   const columns = $derived<DataTableColumn<Row>[]>([
     { key: "name", label: i18n.t.users.name, sortable: true },
     { key: "email", label: i18n.t.users.email, sortable: true },
-    { key: "role", label: i18n.t.users.role, sortable: true },
-    { key: "status", label: i18n.t.users.status },
-    { key: "createdAt", label: i18n.t.users.joined, sortable: true, value: (u) => (u.createdAt ? new Date(u.createdAt).getTime() : 0) },
+    { key: "role", label: i18n.t.users.role, sortable: true, hideBelow: "md" },
+    { key: "status", label: i18n.t.users.status, hideBelow: "lg" },
+    {
+      key: "createdAt",
+      label: i18n.t.users.joined,
+      sortable: true,
+      hideBelow: "lg",
+      value: (u) => (u.createdAt ? new Date(u.createdAt).getTime() : 0),
+    },
     { key: "actions", label: "", class: "w-10" },
   ]);
   const filters = $derived<ToolbarFilter[]>([
@@ -380,13 +387,14 @@
     bind:sort
     bind:page
     perPage={PAGE_SIZE}
+    ariaLabel={i18n.t.users.title}
     label={fmt(i18n.t.users.total, { count: filtered.length })}
   >
-    {#snippet row(user)}
-      <Table.Cell class="font-medium">{user.name}</Table.Cell>
-      <Table.Cell class="text-muted-foreground">{user.email}</Table.Cell>
-      <Table.Cell><Badge variant={user.role === "admin" ? "default" : "secondary"}>{user.role ?? "user"}</Badge></Table.Cell>
-      <Table.Cell>
+    {#snippet row(user, { cellClass })}
+      <Table.Cell class={cn(cellClass("name"), "font-medium")}>{user.name}</Table.Cell>
+      <Table.Cell class={cn(cellClass("email"), "text-muted-foreground")}>{user.email}</Table.Cell>
+      <Table.Cell class={cellClass("role")}><Badge variant={user.role === "admin" ? "default" : "secondary"}>{user.role ?? "user"}</Badge></Table.Cell>
+      <Table.Cell class={cellClass("status")}>
         <div class="flex flex-wrap gap-1">
           {#if user.signupApproved === false}
             <Badge variant="secondary">{i18n.t.users.pendingApproval}</Badge>
@@ -400,8 +408,8 @@
           {/if}
         </div>
       </Table.Cell>
-      <Table.Cell class="text-muted-foreground">{user.createdAt ? formatDateTime(user.createdAt) : "—"}</Table.Cell>
-      <Table.Cell>
+      <Table.Cell class={cn(cellClass("createdAt"), "text-muted-foreground")}>{user.createdAt ? formatDateTime(user.createdAt) : "—"}</Table.Cell>
+      <Table.Cell class={cellClass("actions")}>
         <DropdownMenu.Root>
           <DropdownMenu.Trigger>
             {#snippet child({ props })}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/+layout.server.ts

@@ -1,51 +1,6 @@
-import { redirect } from "@sveltejs/kit";
 import type { LayoutServerLoad } from "./$types";
-import type { Capabilities } from "@podosoft/podokit-api-client";
-import { requireBackendAvailable } from "$lib/server/guards";
+import { loadProtectedLayout } from "$lib/server/protected-layout";
 
 export const load: LayoutServerLoad = async ({ locals, fetch }) => {
-  requireBackendAvailable(locals);
-
-  let capabilities: Capabilities = {
-    twoFactor: false,
-    providers: [],
-    deleteAccount: false,
-    auditLog: false,
-    emailVerification: false,
-    signupApprovalRequired: false,
-    passwordBreachCheck: false,
-    magicLink: false,
-    emailOtp: false,
-    username: false,
-    multiSession: false,
-    phoneNumber: false,
-    apiKey: false,
-    passkey: false,
-    organization: false,
-    oidcProvider: false,
-    roles: ["admin", "user"],
-  };
-  try {
-    const res = await fetch("/api/account/capabilities");
-    if (res.ok) capabilities = (await res.json()) as Capabilities;
-  } catch {
-    /* keep defaults */
-  }
-
-  // Require-two-factor policy: a signed-in user who hasn't enrolled is sent to the
-  // enrolment page until they do (the API's TwoFactorRequiredGuard is the real
-  // boundary; this is the UX). /setup-2fa lives outside this layout, so no loop.
-  const user = locals.user as (App.Locals["user"] & { twoFactorEnabled?: boolean }) | null;
-  let mustEnrol = false;
-  if (user && !user.twoFactorEnabled) {
-    try {
-      const res = await fetch("/api/account/require-2fa");
-      mustEnrol = res.ok && ((await res.json()) as { require2fa?: boolean }).require2fa === true;
-    } catch {
-      /* don't block the app if the policy check fails */
-    }
-  }
-  if (mustEnrol) redirect(302, "/setup-2fa");
-
-  return { user: locals.user, impersonating: !!locals.session?.impersonatedBy, capabilities };
+  return loadProtectedLayout({ locals, fetch });
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+page.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { page } from "$app/state";
+  import AccountMenu from "$lib/components/account-menu.svelte";
   import { Button } from "$lib/components/ui/button";
   import LanguageSwitch from "$lib/components/language-switch.svelte";
   import ThemeToggle from "$lib/components/theme-toggle.svelte";
@@ -6,12 +8,14 @@
   import { getI18n } from "$lib/i18n";
 
   const i18n = getI18n();
+  const user = $derived(page.data.user ?? null);
 </script>
 
 <div class="flex min-h-svh flex-col">
   <header class="flex items-center justify-end gap-2 p-4">
     <LanguageSwitch />
     <ThemeToggle />
+    <AccountMenu {user} />
   </header>
   <main class="flex flex-1 flex-col items-center justify-center gap-6 px-4 text-center">
     <div class="flex flex-col gap-3">

package/dist/templates/modules/admin-dashboard/files/dot-claude/skills/podokit-data-table/SKILL.md

@@ -13,19 +13,20 @@ put pagination outside the table.
 ```svelte
 <script lang="ts">
   import DataTable from "$lib/components/data-table.svelte";
+  import { cn } from "$lib/utils";
   const columns = [
     { key: "name", label: "Name", sortable: true },
     { key: "email", label: "Email", sortable: true },
-    { key: "role", label: "Role", sortable: true },     // action/status columns: no `sortable`
+    { key: "role", label: "Role", sortable: true, hideBelow: "md" },
   ];
   let { rows } = $props();   // Svelte 5 runes only
 </script>
 
-<DataTable {columns} {rows} label="{rows.length} users">
-  {#snippet row(item)}
-    <Table.Cell>{item.name}</Table.Cell>
-    <Table.Cell>{item.email}</Table.Cell>
-    <Table.Cell>{item.role}</Table.Cell>
+<DataTable {columns} {rows} ariaLabel="Users" label="{rows.length} users">
+  {#snippet row(item, { cellClass })}
+    <Table.Cell class={cellClass("name")}>{item.name}</Table.Cell>
+    <Table.Cell class={cellClass("email")}>{item.email}</Table.Cell>
+    <Table.Cell class={cn(cellClass("role"), "text-muted-foreground")}>{item.role}</Table.Cell>
   {/snippet}
 </DataTable>
 ```
@@ -34,6 +35,10 @@ put pagination outside the table.
 - **Server data** (huge lists): use `manualSort` + `manualPagination` + `total`
   + `onChange` (re-fetch with `sortBy`/`sortDirection`/`page`).
 - Nested/derived sort keys: give the column a `value` accessor.
+- Responsive columns: set `hideBelow` to `sm`, `md`, `lg`, or `xl`, then apply
+  `cellClass(columnKey)` to the matching `Table.Cell`. Never repeat the
+  responsive class by hand; the shared class keeps headers and cells aligned.
+- Give each table an `ariaLabel` and scope Playwright locators to that table.
 - No footer needed: `perPage={0}`.
 - **Search & filters**: put the shared `table-toolbar.svelte` (`TableToolbar`)
   above the DataTable. Filters + search apply together on the Search button/Enter