@suphark/ui 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.24.0] — 2026-10-02
+
+เติมของเดิมตามที่สำรวจ shadcnstudio.com (หยิบเฉพาะ "หน้าที่" ที่ยังไม่มี ทำเป็นตัวเดียว + props) — เพิ่มอย่างเดียว ค่าเริ่มต้นหน้าตาเดิม
+
+### Added
+
+- **`TextareaField`** — ช่องข้อความหลายบรรทัดพร้อม `label`/`hint`/`error` + **ตัวนับตัวอักษร** เมื่อมี `maxLength` (แดงเมื่อเต็ม, screen reader อ่าน "พิมพ์แล้ว x จาก y ตัวอักษร" ผ่าน `aria-describedby`) + `minRows`/`maxRows` (Textarea ขยายตามเนื้อหาอยู่แล้ว — `maxRows` จำกัดแล้วเลื่อนใน); controlled/uncontrolled; `textareaClassName`
+- **`UserAvatars`** — รูปผู้ใช้ซ้อนกัน + "+N" จาก array (`users`, `max`, `size` sm|default|lg, `label` นำหน้ารายชื่อให้ screen reader) ชี้ที่ "+N" เห็นชื่อที่เหลือ; ใช้จาก server component ได้ — แทน AvatarGroup + Avatar×N + AvatarGroupCount
+- **จุดสถานะ** `status?: "online" | "away" | "busy" | "offline"` ที่ `Initials`, `UserIdentity` และรายการของ `UserAvatars` (`PresenceDot` + `type Presence` export ด้วย) ใช้ token success/warning/destructive/muted
+- **`TableSkeleton`** (`rows`, `columns`, `header`), **`ListSkeleton`** (`rows`, `avatar`, `lines`), **`CardSkeleton`** (`count`, `variant` stat|content) — โครงระหว่างโหลดสำเร็จรูปสำหรับ `loading.tsx` มี `role="status"` + "กำลังโหลด…" ความกว้างสลับแบบคงที่ (ไม่ random → ไม่ hydration mismatch)
+- **`Notice`**: `icon` (true = ไอคอนตามโทน หรือส่งเอง) และ `dismissible` + `onDismiss` (ปุ่ม X อ่าน `UiText.close`) — ไม่ส่ง = หน้าตาเดิม; ไฟล์เป็น `"use client"` แล้ว (ใช้จาก server component ได้เหมือนเดิม)
+- **`AuthLayout`**: `size?: "sm" | "md" | "lg"` ความกว้างการ์ด (ค่าเริ่มต้น sm = เดิม) — หน้า consent/เลือกองค์กรของ Pi Auth ใช้ md (ขอจาก Pi Auth)
+- `UiText` key ใหม่: `loading`, `presence`, `characterCount`
+- showcase: หน้า `/components/{textarea-field,user-avatars,loading-skeletons}` (125 หน้า), demo `notice` มี icon + dismissible; tests 10 กรณี
+
 ## [0.23.0] — 2026-10-02
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "private": false,
   "type": "module",
   "description": "Design system กลางของ Suphark apps: shadcn/ui (base-nova, Base UI, Tailwind v4) + shared components + token/ฟอนต์ Noto Sans Thai Looped — ส่งเป็น source ให้แอป Next transpile เอง",

package/src/components/shared/auth-layout.tsx

@@ -1,6 +1,8 @@
 import { cn } from "@suphark/ui/lib/utils";
 import type { CSSProperties, ReactNode } from "react";
 
+const SIZE = { sm: "max-w-sm", md: "max-w-md", lg: "max-w-lg" } as const;
+
 export interface AuthLayoutProps {
   /** โลโก้เหนือหัวข้อ — element (`<img>`/ไอคอน) หรือไม่ส่ง = ไม่มี */
   logo?: ReactNode;
@@ -28,6 +30,8 @@ export interface AuthLayoutProps {
   brandForeground?: string | null;
   /** เต็มความสูงจอ (ค่าเริ่มต้น true) — false ใช้ฝังในกรอบ เช่นหน้าเอกสาร */
   fullScreen?: boolean;
+  /** ความกว้างการ์ด: sm = max-w-sm (ค่าเริ่มต้น ฟอร์มล็อกอิน), md = max-w-md (consent/เลือกองค์กร), lg = max-w-lg */
+  size?: "sm" | "md" | "lg";
   className?: string;
 }
 
@@ -57,6 +61,7 @@ export function AuthLayout({
   brandColor,
   brandForeground,
   fullScreen = true,
+  size = "sm",
   className,
 }: AuthLayoutProps) {
   const style = brandColor
@@ -67,7 +72,7 @@ export function AuthLayout({
     : undefined;
 
   const card = (
-    <div className="flex w-full max-w-sm flex-col gap-6">
+    <div className={cn("flex w-full flex-col gap-6", SIZE[size])}>
       <div
         data-slot="auth-card"
         className="overflow-hidden rounded-2xl border bg-card text-card-foreground shadow-lg shadow-foreground/5"

package/src/components/shared/form/textarea-field.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { Field, FieldDescription, FieldError, FieldLabel } from "@suphark/ui/components/ui/field";
+import { Textarea } from "@suphark/ui/components/ui/textarea";
+import { cn } from "@suphark/ui/lib/utils";
+import { type ComponentProps, type CSSProperties, type ReactNode, useId, useState } from "react";
+import { useUiText } from "../ui-text";
+
+/** ความสูงตามจำนวนบรรทัด: บรรทัด × line-height + py-2 (1rem) + เส้นขอบ 2px */
+const rowsHeight = (rows: number) => `calc(${rows}lh + 1rem + 2px)`;
+
+/**
+ * ช่องข้อความหลายบรรทัดพร้อม label/hint/error + ตัวนับตัวอักษร — แทน LabeledField + Textarea + state นับเอง
+ * Textarea ขยายตามเนื้อหาอยู่แล้ว (field-sizing) — `maxRows` จำกัดความสูงแล้วเลื่อนใน, `minRows` ความสูงเริ่มต้น
+ * ตัวนับโผล่เมื่อมี `maxLength` (ปิดด้วย `showCount={false}`) ใช้ได้ทั้ง controlled (`value`) และ uncontrolled (`defaultValue` + `name`)
+ *
+ *   <TextareaField name="bio" label="แนะนำตัว" hint="แสดงในโปรไฟล์" maxLength={280} maxRows={8} />
+ */
+export function TextareaField({
+  label,
+  hint,
+  error,
+  showCount,
+  minRows,
+  maxRows,
+  className,
+  textareaClassName,
+  id,
+  style,
+  onChange,
+  ...props
+}: Omit<ComponentProps<typeof Textarea>, "children"> & {
+  label: ReactNode;
+  /** ข้อความช่วยใต้ช่อง — ซ่อนเมื่อมี error */
+  hint?: ReactNode;
+  error?: ReactNode;
+  /** ค่าเริ่มต้น = true เมื่อมี maxLength */
+  showCount?: boolean;
+  minRows?: number;
+  maxRows?: number;
+  /** className ของ textarea (`className` อยู่ที่กล่อง Field) */
+  textareaClassName?: string;
+}) {
+  const text = useUiText();
+  const autoId = useId();
+  const inputId = id ?? autoId;
+  const countId = `${inputId}-count`;
+  const [uncontrolledLength, setUncontrolledLength] = useState(
+    () => String(props.defaultValue ?? "").length,
+  );
+  const length = props.value != null ? String(props.value).length : uncontrolledLength;
+  const max = props.maxLength;
+  const counting = (showCount ?? max != null) && max != null;
+  const sizeStyle: CSSProperties = {
+    ...(minRows ? { minHeight: rowsHeight(minRows) } : null),
+    ...(maxRows ? { maxHeight: rowsHeight(maxRows) } : null),
+    ...style,
+  };
+
+  return (
+    <Field
+      data-slot="textarea-field"
+      className={cn("gap-1.5", className)}
+      data-invalid={error ? true : undefined}
+    >
+      <FieldLabel htmlFor={inputId} className="font-medium text-sm">
+        {label}
+      </FieldLabel>
+      <Textarea
+        id={inputId}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={counting ? countId : undefined}
+        className={textareaClassName}
+        style={sizeStyle}
+        onChange={(e) => {
+          setUncontrolledLength(e.currentTarget.value.length);
+          onChange?.(e);
+        }}
+        {...props}
+      />
+      {(error || hint || counting) && (
+        <div className="flex items-start gap-2">
+          {error ? (
+            <FieldError className="text-xs">{error}</FieldError>
+          ) : (
+            hint && <FieldDescription className="text-xs">{hint}</FieldDescription>
+          )}
+          {counting && (
+            <span
+              className={cn(
+                "ml-auto shrink-0 text-xs tabular-nums",
+                length >= max ? "text-destructive" : "text-muted-foreground",
+              )}
+            >
+              <span aria-hidden>
+                {length}/{max}
+              </span>
+              <span id={countId} className="sr-only">
+                {(text.characterCount ?? "พิมพ์แล้ว {count} จาก {max} ตัวอักษร")
+                  .replace("{count}", String(length))
+                  .replace("{max}", String(max))}
+              </span>
+            </span>
+          )}
+        </div>
+      )}
+    </Field>
+  );
+}

package/src/components/shared/initials.tsx

@@ -1,6 +1,7 @@
 import { Avatar, AvatarFallback, AvatarImage } from "@suphark/ui/components/ui/avatar";
 import { cn } from "@suphark/ui/lib/utils";
 import type { ComponentProps } from "react";
+import { type Presence, PresenceDot } from "./presence-dot";
 
 /** ตัวอักษรย่อจากชื่อ (ไทย/อังกฤษ): "สมชาย ใจดี" → "สจ", "Suphark A." → "SA" */
 export function initialsOf(name: string | null | undefined, fallback = "?"): string {
@@ -11,13 +12,20 @@ export function initialsOf(name: string | null | undefined, fallback = "?"): str
   return (first + last).toUpperCase();
 }
 
-/** Avatar ของ shadcn + ตัวย่อชื่อ + สีพื้นคงที่ต่อชื่อ (ไม่ต้องมีรูป) */
+/** Avatar ของ shadcn + ตัวย่อชื่อ + สีพื้นคงที่ต่อชื่อ (ไม่ต้องมีรูป) + จุดสถานะ `status` */
 export function Initials({
   name,
   src,
+  status,
   className,
+  children,
   ...props
-}: ComponentProps<typeof Avatar> & { name: string | null | undefined; src?: string | null }) {
+}: ComponentProps<typeof Avatar> & {
+  name: string | null | undefined;
+  src?: string | null;
+  /** จุดสถานะมุมล่างขวา: online / away / busy / offline */
+  status?: Presence;
+}) {
   const hue = [...(name ?? "")].reduce((h, c) => (h * 31 + c.codePointAt(0)!) % 360, 7);
   return (
     <Avatar className={cn("shrink-0", className)} {...props}>
@@ -28,6 +36,8 @@ export function Initials({
       >
         {initialsOf(name)}
       </AvatarFallback>
+      {status && <PresenceDot status={status} />}
+      {children}
     </Avatar>
   );
 }

package/src/components/shared/notice.tsx

@@ -1,7 +1,12 @@
-import { Alert, AlertDescription, AlertTitle } from "@suphark/ui/components/ui/alert";
+"use client";
+
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "@suphark/ui/components/ui/alert";
+import { Button } from "@suphark/ui/components/ui/button";
 import { cn } from "@suphark/ui/lib/utils";
-import type { ComponentProps, ReactNode } from "react";
+import { CircleAlertIcon, CircleCheckIcon, InfoIcon, TriangleAlertIcon, XIcon } from "lucide-react";
+import { type ComponentProps, type ReactNode, useState } from "react";
 import type { Tone } from "./status-badge";
+import { useUiText } from "./ui-text";
 
 export type NoticeTone = Exclude<Tone, "neutral">;
 
@@ -13,21 +18,66 @@ const TONE: Record<NoticeTone, string> = {
   danger: "border-destructive-border bg-destructive-subtle text-destructive-subtle-foreground",
 };
 
-/** Alert ของ shadcn + สีตามความหมาย (info/success/warning/danger) */
+const TONE_ICON: Record<NoticeTone, ReactNode> = {
+  info: <InfoIcon />,
+  success: <CircleCheckIcon />,
+  warning: <TriangleAlertIcon />,
+  danger: <CircleAlertIcon />,
+};
+
+/**
+ * Alert ของ shadcn + สีตามความหมาย (info/success/warning/danger)
+ * `icon` = true ใช้ไอคอนตามโทน หรือส่งไอคอนเอง · `dismissible` = มีปุ่ม X ซ่อนเองเมื่อกด (+ `onDismiss` เช่นจำไว้ใน cookie)
+ *
+ *   <Notice tone="warning" icon dismissible title="ยังไม่ได้ยืนยันอีเมล">ตรวจกล่องจดหมาย…</Notice>
+ */
 export function Notice({
   tone = "info",
   title,
+  icon,
+  dismissible = false,
+  onDismiss,
   children,
   className,
   ...props
 }: Omit<ComponentProps<typeof Alert>, "variant" | "title"> & {
   tone?: NoticeTone;
   title?: ReactNode;
+  /** true = ไอคอนตามโทน, ReactNode = ไอคอนเอง */
+  icon?: ReactNode | boolean;
+  /** แสดงปุ่มปิด (UiText.close) — กดแล้วซ่อนกล่องนี้ */
+  dismissible?: boolean;
+  onDismiss?: () => void;
 }) {
+  const closeLabel = useUiText().close ?? "ปิด";
+  const [hidden, setHidden] = useState(false);
+  if (hidden) return null;
+  const iconNode = icon === true ? TONE_ICON[tone] : icon || null;
   return (
-    <Alert className={cn(TONE[tone], className)} {...props}>
+    <Alert
+      className={cn(TONE[tone], dismissible && "has-data-[slot=alert-action]:pr-9", className)}
+      {...props}
+    >
+      {iconNode}
       {title && <AlertTitle>{title}</AlertTitle>}
       <AlertDescription className="text-inherit">{children}</AlertDescription>
+      {dismissible && (
+        <AlertAction className="top-1.5 right-1.5">
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-xs"
+            aria-label={closeLabel}
+            className="text-current hover:bg-current/10 hover:text-current"
+            onClick={() => {
+              setHidden(true);
+              onDismiss?.();
+            }}
+          >
+            <XIcon />
+          </Button>
+        </AlertAction>
+      )}
     </Alert>
   );
 }

package/src/components/shared/presence-dot.tsx

@@ -0,0 +1,31 @@
+"use client";
+
+import { AvatarBadge } from "@suphark/ui/components/ui/avatar";
+import { cn } from "@suphark/ui/lib/utils";
+import { useUiText } from "./ui-text";
+
+export type Presence = "online" | "away" | "busy" | "offline";
+
+const PRESENCE_CLASS: Record<Presence, string> = {
+  online: "bg-success",
+  away: "bg-warning",
+  busy: "bg-destructive",
+  offline: "bg-muted-foreground",
+};
+
+const PRESENCE_TH: Record<Presence, string> = {
+  online: "ออนไลน์",
+  away: "ไม่อยู่",
+  busy: "ไม่ว่าง",
+  offline: "ออฟไลน์",
+};
+
+/** จุดสถานะมุมล่างขวาของ Avatar (ใช้ใน `Initials status`) — ชื่อสถานะอ่านได้ด้วย screen reader */
+export function PresenceDot({ status, className }: { status: Presence; className?: string }) {
+  const label = useUiText().presence?.[status] ?? PRESENCE_TH[status];
+  return (
+    <AvatarBadge data-presence={status} className={cn(PRESENCE_CLASS[status], className)}>
+      <span className="sr-only">{label}</span>
+    </AvatarBadge>
+  );
+}

package/src/components/shared/skeletons.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import { Skeleton } from "@suphark/ui/components/ui/skeleton";
+import { cn } from "@suphark/ui/lib/utils";
+import type { ReactNode } from "react";
+import { useUiText } from "./ui-text";
+
+/** ความกว้างสลับกันให้ดูเป็นข้อความจริง (คงที่ทุก render — ไม่ใช้ random กัน hydration mismatch) */
+const WIDTHS = ["w-3/4", "w-1/2", "w-2/3", "w-5/6", "w-2/5"] as const;
+const widthAt = (i: number) => WIDTHS[i % WIDTHS.length];
+
+const GRID_COLS: Record<number, string> = {
+  1: "",
+  2: "sm:grid-cols-2",
+  3: "sm:grid-cols-2 lg:grid-cols-3",
+  4: "sm:grid-cols-2 lg:grid-cols-4",
+};
+
+/** กล่องนอกของ skeleton: role=status + ข้อความ "กำลังโหลด…" สำหรับ screen reader */
+function LoadingRegion({
+  slot,
+  label,
+  className,
+  children,
+}: {
+  slot: string;
+  label?: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  const text = useUiText().loading ?? "กำลังโหลด…";
+  return (
+    <div data-slot={slot} role="status" aria-busy="true" className={className}>
+      <span className="sr-only">{label ?? text}</span>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * โครงตารางระหว่างโหลด (loading.tsx ของหน้ารายการ) — หัวตาราง + แถวตามจำนวน คอลัมน์แรกกว้างกว่า
+ *
+ *   export default function Loading() { return <TableSkeleton rows={8} columns={5} /> }
+ */
+export function TableSkeleton({
+  rows = 5,
+  columns = 4,
+  header = true,
+  label,
+  className,
+}: {
+  rows?: number;
+  columns?: number;
+  /** แสดงแถวหัวตาราง */
+  header?: boolean;
+  /** ข้อความ screen reader (ค่าเริ่มต้น UiText.loading) */
+  label?: string;
+  className?: string;
+}) {
+  const template = { gridTemplateColumns: `2fr repeat(${Math.max(columns - 1, 0)}, 1fr)` };
+  const cols = Array.from({ length: columns }, (_, c) => c);
+  return (
+    <LoadingRegion
+      slot="table-skeleton"
+      label={label}
+      className={cn("overflow-hidden rounded-lg border", className)}
+    >
+      {header && (
+        <div className="grid items-center gap-4 border-b bg-muted/50 px-3 py-2.5" style={template}>
+          {cols.map((c) => (
+            <Skeleton key={c} className="h-3.5 w-1/2" />
+          ))}
+        </div>
+      )}
+      {Array.from({ length: rows }, (_, r) => (
+        <div
+          // biome-ignore lint/suspicious/noArrayIndexKey: แถวโครงคงที่ ไม่มีการเรียงใหม่
+          key={r}
+          className="grid items-center gap-4 border-b px-3 py-3 last:border-b-0"
+          style={template}
+        >
+          {cols.map((c) => (
+            <Skeleton key={c} className={cn("h-4", widthAt(r + c))} />
+          ))}
+        </div>
+      ))}
+    </LoadingRegion>
+  );
+}
+
+/**
+ * โครงรายการระหว่างโหลด — avatar (เลือกได้) + ข้อความ 1–2 บรรทัดต่อแถว
+ *
+ *   <ListSkeleton rows={4} avatar lines={2} />
+ */
+export function ListSkeleton({
+  rows = 5,
+  avatar = true,
+  lines = 2,
+  label,
+  className,
+}: {
+  rows?: number;
+  avatar?: boolean;
+  /** จำนวนบรรทัดข้อความต่อแถว (1 หรือ 2) */
+  lines?: 1 | 2;
+  label?: string;
+  className?: string;
+}) {
+  return (
+    <LoadingRegion
+      slot="list-skeleton"
+      label={label}
+      className={cn("flex flex-col gap-4", className)}
+    >
+      {Array.from({ length: rows }, (_, r) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: แถวโครงคงที่ ไม่มีการเรียงใหม่
+        <div key={r} className="flex items-center gap-3">
+          {avatar && <Skeleton className="size-9 shrink-0 rounded-full" />}
+          <div className="flex min-w-0 flex-1 flex-col gap-2">
+            <Skeleton className={cn("h-4", widthAt(r))} />
+            {lines === 2 && <Skeleton className={cn("h-3", widthAt(r + 2))} />}
+          </div>
+        </div>
+      ))}
+    </LoadingRegion>
+  );
+}
+
+/**
+ * โครงการ์ดระหว่างโหลด — การ์ดตัวเลข (`variant="stat"` ค่าเริ่มต้น แบบ StatGrid) หรือการ์ดเนื้อหา (`variant="content"`)
+ *
+ *   <CardSkeleton count={4} />   <CardSkeleton count={3} variant="content" />
+ */
+export function CardSkeleton({
+  count = 3,
+  variant = "stat",
+  label,
+  className,
+}: {
+  count?: number;
+  variant?: "stat" | "content";
+  label?: string;
+  className?: string;
+}) {
+  return (
+    <LoadingRegion
+      slot="card-skeleton"
+      label={label}
+      className={cn("grid gap-4", GRID_COLS[Math.min(Math.max(count, 1), 4)], className)}
+    >
+      {Array.from({ length: count }, (_, i) => (
+        <div
+          // biome-ignore lint/suspicious/noArrayIndexKey: การ์ดโครงคงที่ ไม่มีการเรียงใหม่
+          key={i}
+          className="flex flex-col gap-3 rounded-xl border bg-card p-4"
+        >
+          {variant === "stat" ? (
+            <>
+              <Skeleton className="h-3.5 w-1/2" />
+              <Skeleton className="h-7 w-2/3" />
+              <Skeleton className="h-3 w-1/3" />
+            </>
+          ) : (
+            <>
+              <Skeleton className="h-5 w-2/3" />
+              <Skeleton className="h-3.5 w-full" />
+              <Skeleton className={cn("h-3.5", widthAt(i))} />
+              <Skeleton className="mt-2 h-8 w-24" />
+            </>
+          )}
+        </div>
+      ))}
+    </LoadingRegion>
+  );
+}

package/src/components/shared/ui-text.tsx

@@ -83,6 +83,12 @@ export interface UiText {
   chat?: Partial<{ placeholder: string; send: string; typing: string; scrollToLatest: string }>;
   /** SimplePagination (optional) */
   pagination?: Partial<{ previous: string; next: string; label: string; page: string }>;
+  /** TableSkeleton/ListSkeleton/CardSkeleton (optional) — ข้อความสำหรับ screen reader */
+  loading?: string;
+  /** สถานะออนไลน์ของ UserIdentity/Initials (optional) */
+  presence?: Partial<{ online: string; away: string; busy: string; offline: string }>;
+  /** TextareaField (optional) — ข้อความ screen reader ของตัวนับ ใช้ {count} {max} */
+  characterCount?: string;
 }
 
 export const UI_TEXT_TH: UiText = {
@@ -147,6 +153,9 @@ export const UI_TEXT_TH: UiText = {
     scrollToLatest: "ไปข้อความล่าสุด",
   },
   pagination: { previous: "ก่อนหน้า", next: "ถัดไป", label: "แบ่งหน้า", page: "หน้า" },
+  loading: "กำลังโหลด…",
+  presence: { online: "ออนไลน์", away: "ไม่อยู่", busy: "ไม่ว่าง", offline: "ออฟไลน์" },
+  characterCount: "พิมพ์แล้ว {count} จาก {max} ตัวอักษร",
 };
 
 export const UI_TEXT_EN: UiText = {
@@ -211,6 +220,9 @@ export const UI_TEXT_EN: UiText = {
     scrollToLatest: "Jump to latest",
   },
   pagination: { previous: "Previous", next: "Next", label: "Pagination", page: "Page" },
+  loading: "Loading…",
+  presence: { online: "Online", away: "Away", busy: "Busy", offline: "Offline" },
+  characterCount: "{count} of {max} characters",
 };
 
 const UiTextContext = createContext<UiText>(UI_TEXT_TH);

package/src/components/shared/user-avatars.tsx

@@ -0,0 +1,68 @@
+import { AvatarGroup, AvatarGroupCount } from "@suphark/ui/components/ui/avatar";
+import { Initials } from "./initials";
+import type { Presence } from "./presence-dot";
+
+export interface UserAvatarItem {
+  /** key ของ React (ไม่ส่ง = ใช้ชื่อ) */
+  id?: string;
+  name: string | null | undefined;
+  src?: string | null;
+  status?: Presence;
+}
+
+/**
+ * รูปผู้ใช้ซ้อนกัน + "+N" — ผู้รับผิดชอบงาน, สมาชิกทีม, คนที่ดูอยู่ (แทน AvatarGroup + Avatar + AvatarImage + AvatarFallback + AvatarGroupCount)
+ * ไม่มีรูป = ตัวย่อชื่อสีคงที่ต่อชื่อ; ชี้ที่รูปเห็นชื่อ, ที่ "+N" เห็นชื่อที่เหลือ; screen reader อ่านชื่อทั้งหมด
+ * ใช้จาก server component ได้
+ *
+ *   <UserAvatars users={task.assignees} max={3} size="sm" />
+ */
+export function UserAvatars({
+  users,
+  max = 4,
+  size = "default",
+  label,
+  className,
+}: {
+  users: ReadonlyArray<UserAvatarItem>;
+  /** จำนวนรูปที่แสดงก่อนรวบเป็น "+N" (นับรวมช่อง +N) */
+  max?: number;
+  size?: "sm" | "default" | "lg";
+  /** ข้อความนำหน้ารายชื่อสำหรับ screen reader เช่น "ผู้รับผิดชอบ" */
+  label?: string;
+  className?: string;
+}) {
+  const overflow = users.length > max;
+  const shown = overflow ? users.slice(0, Math.max(max - 1, 1)) : users;
+  const rest = users.slice(shown.length);
+  const names = users.map((u) => u.name?.trim() || "—").join(", ");
+  return (
+    <AvatarGroup
+      data-slot="user-avatars"
+      role="group"
+      aria-label={label ? `${label}: ${names}` : names}
+      className={className}
+    >
+      {shown.map((u, i) => (
+        <Initials
+          key={u.id ?? `${u.name ?? ""}-${i}`}
+          name={u.name}
+          src={u.src}
+          status={u.status}
+          size={size}
+          title={u.name ?? undefined}
+          aria-hidden
+        />
+      ))}
+      {rest.length > 0 && (
+        <AvatarGroupCount
+          aria-hidden
+          title={rest.map((u) => u.name?.trim() || "—").join(", ")}
+          className="text-label font-medium"
+        >
+          +{rest.length}
+        </AvatarGroupCount>
+      )}
+    </AvatarGroup>
+  );
+}

package/src/components/shared/user-identity.tsx

@@ -1,6 +1,7 @@
 import { Initials } from "@suphark/ui/components/shared/initials";
 import { cn } from "@suphark/ui/lib/utils";
 import type { ReactNode } from "react";
+import type { Presence } from "./presence-dot";
 
 export interface UserIdentityProps {
   name: string | null | undefined;
@@ -14,6 +15,8 @@ export interface UserIdentityProps {
   hint?: ReactNode;
   /** sm = ใช้ในแถวตาราง (avatar size-7), default = size-9 */
   size?: "sm" | "default";
+  /** จุดสถานะบน avatar: online / away / busy / offline */
+  status?: Presence;
   /** ซ่อน avatar (เมื่อแถวมีรูปอยู่แล้ว) */
   hideAvatar?: boolean;
   className?: string;
@@ -30,6 +33,7 @@ export function UserIdentity({
   badge,
   hint,
   size = "default",
+  status,
   hideAvatar = false,
   className,
 }: UserIdentityProps) {
@@ -43,6 +47,7 @@ export function UserIdentity({
         <Initials
           name={displayName ?? (typeof email === "string" ? email : "")}
           src={src}
+          status={status}
           className={size === "sm" ? "size-7" : "size-9"}
         />
       )}

package/src/index.ts

@@ -100,6 +100,7 @@ export {
   type SimpleSelectProps,
 } from "./components/shared/form/simple-select";
 export { SliderField, type SliderFieldProps } from "./components/shared/form/slider-field";
+export { TextareaField } from "./components/shared/form/textarea-field";
 export {
   type FormAction,
   FormMessage,
@@ -142,6 +143,7 @@ export { Notice, type NoticeTone } from "./components/shared/notice";
 export { type DecimalLike, FormattedNumber } from "./components/shared/number/formatted-number";
 export { PageHeader } from "./components/shared/page-header";
 export { PageSkeleton } from "./components/shared/page-skeleton";
+export { type Presence, PresenceDot } from "./components/shared/presence-dot";
 export { ProgressBar, type ProgressTone } from "./components/shared/progress-bar";
 export {
   describeCondition,
@@ -180,6 +182,7 @@ export {
   SimpleTabs,
 } from "./components/shared/simple-tabs";
 export { SimplePopover, SimpleTooltip } from "./components/shared/simple-tooltip";
+export { CardSkeleton, ListSkeleton, TableSkeleton } from "./components/shared/skeletons";
 export { SkipLink } from "./components/shared/skip-link";
 export { Stat, type StatDelta, StatGrid, type StatTone } from "./components/shared/stat";
 export { StatusBadge, statusTone, type Tone } from "./components/shared/status-badge";
@@ -206,6 +209,7 @@ export {
   type UploadListText,
   type UploadStatus,
 } from "./components/shared/upload-list";
+export { type UserAvatarItem, UserAvatars } from "./components/shared/user-avatars";
 export { UserIdentity, type UserIdentityProps } from "./components/shared/user-identity";
 // ---------- shadcn/ui primitives ----------
 export * from "./components/ui/accordion";