@suphark/ui 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.3.0] — 2026-09-18
+
+### Added
+
+- **AppShell** (`@suphark/ui/next`) — โครงแอปกลางแทน ConsoleShell ของ Pi Auth และ main layout ของ supplychain: shadcn Sidebar (ยุบเป็นไอคอน/offcanvas/none, Sheet บนมือถือ, ⌘B, cookie `sidebar_state`), โลโก้ `AppBrand` (name/logo/subtitle/version), ค้นหาเมนู, เมนู 2 ชั้น `AppNav` (ไฮไลต์ตาม pathname, กางอัตโนมัติเมื่อลูก active, dropdown เมื่อยุบ, badge, labs, pin ผ่าน `pin` prop), slot `sidebarHeader`/`sidebarFooter`, header (SidebarTrigger + `HeaderBreadcrumbs` อัตโนมัติ + `center`/`actions`/`banner`), `brandColor` ต่อ tenant, `contentMaxWidth`
+- `UserMenu` (variant `sidebar` | `header`): หัวผู้ใช้ + children (ใส่ DropdownMenuItem/ThemeMenuItems เอง) + `onSignOut`
+- `HeaderBreadcrumbs` (labels/skip/hideIds/homeHref), `NavLink` (จาก Pi Auth)
+- โมเดลเมนู `AppNavGroup`/`AppNavItem` (icon เป็น ReactNode — ประกาศใน server component ได้) + helpers `filterNav` (ตัดตามสิทธิ์ทุกชั้น), `searchNav`, `flattenNav`, `isNavActive` (+tests รวม 40)
+- barrel หลัก export `toast` จาก sonner (แอปไม่ต้องติดตั้ง sonner เอง)
+- showcase: `/shell` ตัวอย่าง layout ที่ใช้ AppShell + UserMenu + ThemeMenuItems + filterNav + cookie defaultOpen
+
 ## [0.2.0] — 2026-09-18
 
 ### Added

package/README.md

@@ -55,8 +55,8 @@ import { ThemeProvider, Toaster } from "@suphark/ui";
 // ทุกอย่างที่ไม่พึ่ง Next — primitives, shared, theme, hooks, cn
 import { Button, Card, FormFieldInput, StatusBadge, ThemeToggle, cn } from "@suphark/ui";
 
-// ของที่ใช้ next/navigation หรือ next/link
-import { FormDialog, RowActions, LinkButton, RefreshButton, PageShell } from "@suphark/ui/next";
+// ของที่ใช้ next/navigation หรือ next/link + โครงแอป
+import { AppShell, UserMenu, filterNav, FormDialog, RowActions, LinkButton, RefreshButton, PageShell } from "@suphark/ui/next";
 
 // ตารางข้อมูล (ต้องติดตั้ง @tanstack/react-table เอง)
 import { DataTable, DataTableColumnHeader, useDataTable } from "@suphark/ui/data-table";
@@ -72,11 +72,49 @@ import { ChartContainer } from "@suphark/ui/components/ui/chart";
 | `src/components/ui/*` | shadcn/ui ต้นฉบับ 59 ตัว (+ `__tests__`) | **ห้ามแก้มือ** — เพิ่ม/อัปเดตด้วย `pnpm dlx shadcn@latest add <name>` ใน `packages/ui` (`components.json` ตั้ง alias ไว้แล้ว) |
 | `src/components/shared/*` | ของที่เราประกอบเอง: ปุ่มมาตรฐาน (`button/`), form-field บน react-hook-form (`form/`), layout, theme, combobox, และชุดจาก Pi Auth (FormDialog, NameIdFields, StatusBadge, RowMenu, …) | แก้ได้ แต่คง props เดิมให้มากที่สุด (minor = เพิ่ม, major = เปลี่ยน) |
 | `src/components/data-table/*` | DataTable บน tanstack (toolbar, faceted filter, pagination, view options, row actions, ลากเรียงแถว) | entry `@suphark/ui/data-table` |
+| `src/components/app-shell/*` | AppShell (sidebar + header + เนื้อหา), AppNav, AppBrand, UserMenu, HeaderBreadcrumbs, NavLink, filterNav/searchNav | export ผ่าน `@suphark/ui/next` (ใช้ next/link, next/navigation) |
 | `src/components/design-system/*` | หน้า showcase (render ใน `apps/showcase`) | ไม่อยู่ใน barrel |
 | `src/lib/*`, `src/hooks/*` | `cn`, formatter วันที่ไทย, สีสถานะ, permission context, `useIsMobile`, `useCopyToClipboard` | |
 | `src/styles.css` | token (slate + success/warning/sidebar/chart), radius, ฟอนต์, scrollbar, dark variant | |
 | `scripts/*.mjs` | audit บังคับ: Base UI props (`default*`/`onSelect`), typography scale | แอปปลายทางรันได้จาก `node_modules/@suphark/ui/scripts` |
 
+### โครงแอป (AppShell)
+
+```tsx
+// app/(app)/layout.tsx — server component ได้ (icon เป็น element)
+import { ThemeMenuItems } from "@suphark/ui";
+import { AppShell, type AppNavGroup, filterNav, UserMenu } from "@suphark/ui/next";
+import { cookies } from "next/headers";
+
+const NAV: AppNavGroup[] = [
+  { title: "งาน", items: [
+    { title: "แดชบอร์ด", href: "/", icon: <LayoutDashboard />, exact: true },
+    { title: "จัดซื้อ", icon: <ShoppingCart />, items: [{ title: "แพ็กเกจ", href: "/packages", permission: "package:read" }] },
+  ]},
+];
+
+export default async function Layout({ children }) {
+  const defaultOpen = (await cookies()).get("sidebar_state")?.value !== "false";
+  return (
+    <AppShell
+      brand={{ name: "Pi Auth", subtitle: tenant.name, version: "v1.2.0", versionHref: "/change-log" }}
+      nav={filterNav(NAV, can)}
+      searchable
+      defaultOpen={defaultOpen}
+      brandColor={tenant.primaryColor}
+      header={{ breadcrumbs: { skip: ["console"] }, actions: <NotificationBell /> }}
+      sidebarFooter={<UserMenu user={{ name, email, image }} onSignOut={signOut}><ThemeMenuItems /></UserMenu>}
+    >
+      {children}
+    </AppShell>
+  );
+}
+```
+
+- `header={false}` ไม่มี header · `collapsible="offcanvas"` ซ่อนทั้งแผง (supplychain) · `contentMaxWidth="max-w-5xl"` จำกัดความกว้าง (Pi Auth)
+- `pin={{ pinnedHrefs, onTogglePin }}` เปิดปุ่มปักหมุดเมนู (แอปเก็บ state เอง) · `header.center` วาง pinned menus
+- ตัวอย่างรันได้ที่ `apps/showcase/src/app/shell`
+
 ### สีแบรนด์ต่อ tenant/แอป (`--brand`)
 
 ตั้ง `--brand` / `--brand-foreground` inline บน wrapper (หรือใส่ `data-brand`) แล้ว `primary`/`ring`/`sidebar-primary` ข้างในตามไปด้วย — ค่าเริ่มต้นไม่ตั้ง `--brand` (primary = slate) ดูตัวอย่างที่ `apps/showcase/src/app/brand`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.2.0",
+  "version": "0.3.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 เอง",
@@ -43,6 +43,7 @@
     "./components/shared/button": "./src/components/shared/button/index.ts",
     "./components/shared/theme": "./src/components/shared/theme/index.ts",
     "./components/data-table": "./src/components/data-table/index.ts",
+    "./components/app-shell": "./src/components/app-shell/index.ts",
     "./components/*": "./src/components/*.tsx",
     "./lib/*": "./src/lib/*.ts",
     "./hooks/*": "./src/hooks/*.ts",

package/src/components/app-shell/app-brand.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import {
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  useSidebar,
+} from "@suphark/ui/components/ui/sidebar";
+import { cn } from "@suphark/ui/lib/utils";
+import Link from "next/link";
+import type { ReactNode } from "react";
+
+export interface AppBrandProps {
+  /** ชื่อแอป/องค์กร */
+  name: ReactNode;
+  /** โลโก้ (ไอคอน lucide, <img>, หรือตัวอักษร) — ถ้าไม่ส่งจะใช้ตัวอักษรแรกของ name */
+  logo?: ReactNode;
+  /** ข้อความบรรทัดล่าง เช่น ชื่อ tenant / แผน */
+  subtitle?: ReactNode;
+  /** ลิงก์เมื่อกดโลโก้ (ค่าเริ่มต้น "/") */
+  href?: string;
+  /** ป้ายเล็กด้านขวา เช่น เวอร์ชัน `v1.4.0` — กดแล้วไป `versionHref` (เช่น /change-log) */
+  version?: ReactNode;
+  versionHref?: string;
+  className?: string;
+}
+
+/**
+ * โลโก้ + ชื่อแอปมุมบน sidebar (ยกจาก supplychain NavLogo + Pi Auth ConsoleShell header)
+ * ยุบเป็นไอคอนแล้วเหลือแค่โลโก้
+ */
+export function AppBrand({
+  name,
+  logo,
+  subtitle,
+  href = "/",
+  version,
+  versionHref,
+  className,
+}: AppBrandProps) {
+  const { setOpenMobile } = useSidebar();
+  const closeMobile = () => setOpenMobile(false);
+  const mark = (
+    <div className="flex aspect-square size-8 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-sidebar-primary font-bold text-sidebar-primary-foreground text-sm [&_img]:size-full [&_img]:object-contain [&_svg]:size-4">
+      {logo ?? (typeof name === "string" ? name.charAt(0).toUpperCase() : "•")}
+    </div>
+  );
+  const versionNode =
+    version !== undefined &&
+    (versionHref ? (
+      <Link
+        href={versionHref}
+        onClick={closeMobile}
+        className="shrink-0 rounded-md px-2 py-1 text-muted-foreground text-xs no-underline transition-colors hover:bg-sidebar-accent hover:text-primary group-data-[collapsible=icon]:hidden"
+      >
+        {version}
+      </Link>
+    ) : (
+      <span className="shrink-0 px-2 text-muted-foreground text-xs group-data-[collapsible=icon]:hidden">
+        {version}
+      </span>
+    ));
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem className={cn("flex items-center", className)}>
+        <SidebarMenuButton
+          size="lg"
+          className="min-w-0 flex-1 group-data-[collapsible=icon]:p-0!"
+          render={<Link href={href} onClick={closeMobile} />}
+        >
+          {mark}
+          <div className="grid flex-1 overflow-hidden text-left text-sm leading-tight group-data-[collapsible=icon]:hidden">
+            <span className="truncate font-medium text-sidebar-foreground">{name}</span>
+            {subtitle && <span className="truncate text-muted-foreground text-xs">{subtitle}</span>}
+          </div>
+        </SidebarMenuButton>
+        {versionNode}
+      </SidebarMenuItem>
+    </SidebarMenu>
+  );
+}

package/src/components/app-shell/app-nav.tsx

@@ -0,0 +1,260 @@
+"use client";
+
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@suphark/ui/components/ui/collapsible";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@suphark/ui/components/ui/dropdown-menu";
+import {
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  useSidebar,
+} from "@suphark/ui/components/ui/sidebar";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@suphark/ui/components/ui/tooltip";
+import { cn } from "@suphark/ui/lib/utils";
+import { ChevronRight, FlaskConical, Pin } from "lucide-react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { type AppNavGroup, type AppNavItem, isNavActive } from "./types";
+
+/** ปุ่ม pin — แสดงเมื่อแอปส่ง `pinnedHrefs` + `onTogglePin` (supplychain เก็บใน user preferences) */
+export interface AppNavPinProps {
+  pinnedHrefs?: string[];
+  onTogglePin?: (href: string) => void;
+  pinLabel?: string;
+  unpinLabel?: string;
+}
+
+function MenuTitle({ title, isLabs }: { title: string; isLabs?: boolean }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={<span className="flex w-full items-center gap-1.5 overflow-hidden" />}
+      >
+        <span
+          className={cn("truncate", isLabs && "font-medium text-amber-600 dark:text-amber-500")}
+        >
+          {title}
+        </span>
+        {isLabs && <FlaskConical className="h-3 w-3 shrink-0 text-amber-600 dark:text-amber-500" />}
+      </TooltipTrigger>
+      <TooltipContent side="right" align="center" className="max-w-xs break-words">
+        {title}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function PinAction({
+  href,
+  pin,
+  className,
+}: {
+  href: string;
+  pin: AppNavPinProps;
+  className?: string;
+}) {
+  if (!pin.onTogglePin) return null;
+  const isPinned = pin.pinnedHrefs?.includes(href) ?? false;
+  const label = isPinned ? (pin.unpinLabel ?? "เลิกปักหมุด") : (pin.pinLabel ?? "ปักหมุดที่ header");
+  return (
+    <SidebarMenuAction
+      showOnHover
+      onClick={() => pin.onTogglePin?.(href)}
+      title={label}
+      className={className}
+    >
+      <Pin className={cn("size-3.5", isPinned && "fill-current")} />
+      <span className="sr-only">{label}</span>
+    </SidebarMenuAction>
+  );
+}
+
+/**
+ * กลุ่มเมนูใน sidebar (ยกจาก supplychain NavMain): 2 ชั้น, กางได้, ยุบเป็นไอคอนแล้วเป็น dropdown,
+ * ไฮไลต์ตาม pathname (prefix match), ป้าย badge, ฟีเจอร์ labs, และ pin (ถ้าแอปส่งมา)
+ */
+export function AppNavGroupMenu({
+  group,
+  pin = {},
+  forceOpen = false,
+}: {
+  group: AppNavGroup;
+  pin?: AppNavPinProps;
+  /** กางทุกกลุ่มย่อย (ใช้ตอนค้นหาเมนู) */
+  forceOpen?: boolean;
+}) {
+  const { state, isMobile, setOpenMobile } = useSidebar();
+  const pathname = usePathname();
+  const isCollapsed = state === "collapsed" && !isMobile;
+  // บนมือถือ sidebar เป็น Sheet — กดลิงก์แล้วปิดให้
+  const closeMobile = () => setOpenMobile(false);
+
+  const renderLeaf = (item: AppNavItem & { href: string }) => {
+    const active = isNavActive(pathname, item.href, item.exact);
+    return (
+      <SidebarMenuItem key={item.href}>
+        <SidebarMenuButton
+          isActive={active}
+          tooltip={item.title}
+          render={<Link href={item.href} onClick={closeMobile} />}
+        >
+          {item.icon}
+          <MenuTitle title={item.title} isLabs={item.isLabs} />
+        </SidebarMenuButton>
+        {item.badge !== undefined && <SidebarMenuBadge>{item.badge}</SidebarMenuBadge>}
+        <PinAction href={item.href} pin={pin} />
+      </SidebarMenuItem>
+    );
+  };
+
+  return (
+    <SidebarGroup>
+      {group.title && <SidebarGroupLabel>{group.title}</SidebarGroupLabel>}
+      <SidebarMenu>
+        {group.items.map((item) => {
+          const children = item.items ?? [];
+          const hasChildren = children.length > 0;
+
+          // ใบ (ไม่มีลูก)
+          if (!hasChildren) {
+            if (!item.href) return null;
+            return renderLeaf({ ...item, href: item.href });
+          }
+
+          const childActive = children.some((c) => isNavActive(pathname, c.href, c.exact));
+
+          // ยุบเป็นไอคอน + มีลูก → dropdown ด้านขวา
+          if (isCollapsed) {
+            return (
+              <SidebarMenuItem key={item.title}>
+                <DropdownMenu>
+                  <DropdownMenuTrigger
+                    render={<SidebarMenuButton tooltip={item.title} isActive={childActive} />}
+                  >
+                    {item.icon}
+                    <MenuTitle title={item.title} isLabs={item.isLabs} />
+                    <ChevronRight className="ml-auto" />
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent side="right" align="start" sideOffset={4}>
+                    <DropdownMenuGroup>
+                      <DropdownMenuLabel>{item.title}</DropdownMenuLabel>
+                      <DropdownMenuSeparator />
+                      {children.map((sub) => (
+                        <DropdownMenuItem
+                          key={sub.href ?? sub.title}
+                          render={
+                            <Link
+                              href={sub.href ?? "#"}
+                              className="flex cursor-pointer items-center gap-2"
+                            />
+                          }
+                        >
+                          {sub.icon}
+                          <MenuTitle title={sub.title} isLabs={sub.isLabs} />
+                        </DropdownMenuItem>
+                      ))}
+                    </DropdownMenuGroup>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </SidebarMenuItem>
+            );
+          }
+
+          // กางปกติ — เปิดค้างเมื่อลูกตัวใดตัวหนึ่ง active หรือกำลังค้นหา
+          const open = forceOpen || childActive;
+          return (
+            <Collapsible
+              key={`${item.title}-${open}`}
+              render={<SidebarMenuItem />}
+              defaultOpen={open}
+              className="group/collapsible"
+            >
+              <CollapsibleTrigger
+                render={<SidebarMenuButton tooltip={item.title} suppressHydrationWarning />}
+              >
+                {item.icon}
+                <MenuTitle title={item.title} isLabs={item.isLabs} />
+                <ChevronRight className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
+              </CollapsibleTrigger>
+              <CollapsibleContent suppressHydrationWarning>
+                <SidebarMenuSub>
+                  {children.map((sub) => {
+                    if (!sub.href) return null;
+                    const active = isNavActive(pathname, sub.href, sub.exact);
+                    return (
+                      <SidebarMenuSubItem key={sub.href}>
+                        <SidebarMenuSubButton
+                          isActive={active}
+                          render={
+                            <Link
+                              href={sub.href}
+                              className="flex items-center gap-2"
+                              onClick={closeMobile}
+                            />
+                          }
+                        >
+                          {sub.icon}
+                          <MenuTitle title={sub.title} isLabs={sub.isLabs} />
+                        </SidebarMenuSubButton>
+                        {sub.badge !== undefined && (
+                          <SidebarMenuBadge>{sub.badge}</SidebarMenuBadge>
+                        )}
+                        <PinAction
+                          href={sub.href}
+                          pin={pin}
+                          className="top-1 right-2 opacity-0 transition-opacity group-hover/menu-sub-item:opacity-100"
+                        />
+                      </SidebarMenuSubItem>
+                    );
+                  })}
+                </SidebarMenuSub>
+              </CollapsibleContent>
+            </Collapsible>
+          );
+        })}
+      </SidebarMenu>
+    </SidebarGroup>
+  );
+}
+
+/** ทุกกลุ่มเมนู */
+export function AppNav({
+  nav,
+  pin,
+  forceOpen,
+}: {
+  nav: AppNavGroup[];
+  pin?: AppNavPinProps;
+  forceOpen?: boolean;
+}) {
+  return (
+    <>
+      {nav.map((group, i) => (
+        <AppNavGroupMenu
+          key={group.title ?? `group-${i}`}
+          group={group}
+          pin={pin}
+          forceOpen={forceOpen}
+        />
+      ))}
+    </>
+  );
+}

package/src/components/app-shell/app-shell.tsx

@@ -0,0 +1,270 @@
+"use client";
+
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "@suphark/ui/components/ui/input-group";
+import { Separator } from "@suphark/ui/components/ui/separator";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarInset,
+  SidebarProvider,
+  SidebarRail,
+  SidebarTrigger,
+  useSidebar,
+} from "@suphark/ui/components/ui/sidebar";
+import { cn } from "@suphark/ui/lib/utils";
+import { Search, X } from "lucide-react";
+import {
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { AppBrand, type AppBrandProps } from "./app-brand";
+import { AppNav, type AppNavPinProps } from "./app-nav";
+import { HeaderBreadcrumbs, type HeaderBreadcrumbsProps } from "./header-breadcrumbs";
+import { type AppNavGroup, searchNav } from "./types";
+
+export interface AppShellProps {
+  /** โลโก้/ชื่อแอปมุมบน sidebar */
+  brand: AppBrandProps;
+  /** เมนู (ตัดตามสิทธิ์ด้วย `filterNav` ก่อนส่งเข้ามา) */
+  nav: AppNavGroup[];
+  /** ช่องค้นหาเมนูใต้โลโก้ (supplychain) */
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  /** ปุ่ม pin เมนูขึ้น header (แอปเก็บ state เอง) */
+  pin?: AppNavPinProps;
+  /** ส่วนเพิ่มใน sidebar ใต้โลโก้ เช่น TenantSwitcher / CommandPalette */
+  sidebarHeader?: ReactNode;
+  /** ท้าย sidebar — ปกติคือ `<UserMenu variant="sidebar" />` */
+  sidebarFooter?: ReactNode;
+  /**
+   * header ของเนื้อหา: `false` = ไม่มี header, `true`/ไม่ส่ง = SidebarTrigger + breadcrumb อัตโนมัติ
+   * ส่ง object เพื่อกำหนดเอง
+   */
+  header?:
+    | boolean
+    | {
+        /** breadcrumb: `false` ปิด, object = ตั้งค่า HeaderBreadcrumbs, ReactNode = ใส่เอง */
+        breadcrumbs?: false | HeaderBreadcrumbsProps | ReactNode;
+        /** กลางบรรทัด (เช่น pinned menus) */
+        center?: ReactNode;
+        /** ขวาสุด: notification, feedback, `<UserMenu variant="header" />` … */
+        actions?: ReactNode;
+        /** แถบเหนือ header เช่น impersonation banner */
+        banner?: ReactNode;
+        className?: string;
+      };
+  /** สีแบรนด์ต่อ tenant (ตั้ง --brand บน wrapper → primary/ring/sidebar-primary ตาม) */
+  brandColor?: string | null;
+  brandForeground?: string | null;
+  /** `icon` (ค่าเริ่มต้น) ยุบเหลือไอคอน · `offcanvas` ซ่อนทั้งแผง · `none` ตรึงตลอด */
+  collapsible?: ComponentProps<typeof Sidebar>["collapsible"];
+  /** เปิด sidebar ตอนโหลด (อ่านจาก cookie `sidebar_state` ฝั่ง server แล้วส่งมาได้) */
+  defaultOpen?: boolean;
+  /** class ของกล่องเนื้อหา (ค่าเริ่มต้น padding ตาม supplychain) */
+  contentClassName?: string;
+  /** จำกัดความกว้างเนื้อหา เช่น `max-w-5xl` (Pi Auth) — ไม่ส่ง = เต็มจอ (supplychain) */
+  contentMaxWidth?: string;
+  children: ReactNode;
+}
+
+/**
+ * โครงแอปมาตรฐาน: sidebar ซ้าย (shadcn Sidebar — ยุบเป็นไอคอนบนเดสก์ท็อป, Sheet บนมือถือ) + header + เนื้อหา
+ * ยกจาก supplychain (main layout + AppSidebar) และ Pi Auth ConsoleShell — ใช้จาก layout.tsx ของแอปได้ทั้ง server/client
+ *
+ * ```tsx
+ * <AppShell brand={{ name: "Pi Auth" }} nav={filterNav(NAV, can)}
+ *   sidebarFooter={<UserMenu user={user} onSignOut={signOut}><ThemeMenuItems /></UserMenu>}>
+ *   {children}
+ * </AppShell>
+ * ```
+ */
+export function AppShell({
+  brand,
+  nav,
+  searchable = false,
+  searchPlaceholder = "ค้นหาเมนู…",
+  pin,
+  sidebarHeader,
+  sidebarFooter,
+  header = true,
+  brandColor,
+  brandForeground,
+  collapsible = "icon",
+  defaultOpen = true,
+  contentClassName,
+  contentMaxWidth,
+  children,
+}: AppShellProps) {
+  const style = brandColor
+    ? ({
+        "--brand": brandColor,
+        ...(brandForeground ? { "--brand-foreground": brandForeground } : {}),
+      } as CSSProperties)
+    : undefined;
+
+  const headerOpts = typeof header === "object" ? header : {};
+  const showHeader = header !== false;
+  const breadcrumbs =
+    headerOpts.breadcrumbs === false ? null : headerOpts.breadcrumbs === undefined ||
+      isBreadcrumbOptions(headerOpts.breadcrumbs) ? (
+      <HeaderBreadcrumbs {...(headerOpts.breadcrumbs ?? {})} />
+    ) : (
+      headerOpts.breadcrumbs
+    );
+
+  return (
+    // base-ui-ok: defaultOpen อ่านจาก cookie ครั้งเดียวตอน mount — หลังจากนั้น Sidebar จัดการ state เอง (ตั้งใจให้ uncontrolled)
+    <SidebarProvider defaultOpen={defaultOpen} style={style}>
+      <ShellSidebar
+        brand={brand}
+        nav={nav}
+        searchable={searchable}
+        searchPlaceholder={searchPlaceholder}
+        pin={pin}
+        sidebarHeader={sidebarHeader}
+        sidebarFooter={sidebarFooter}
+        collapsible={collapsible}
+      />
+
+      <SidebarInset>
+        {showHeader && (
+          <div className="sticky top-0 z-40 shrink-0 bg-background print:static">
+            {headerOpts.banner}
+            <header
+              className={cn(
+                "flex h-auto flex-col border-b px-4 md:h-14 md:flex-row md:items-center print:hidden",
+                headerOpts.className,
+              )}
+            >
+              <div className="flex h-12 min-w-0 flex-1 items-center gap-2 md:h-full">
+                <SidebarTrigger className="-ml-1" />
+                {breadcrumbs && (
+                  <>
+                    <Separator orientation="vertical" className="mr-2 hidden h-4 md:block" />
+                    <div className="min-w-0 flex-1">{breadcrumbs}</div>
+                  </>
+                )}
+              </div>
+              {(headerOpts.center || headerOpts.actions) && (
+                <div className="flex h-10 min-w-0 items-center gap-2 pb-1 md:ml-auto md:h-full md:pb-0">
+                  {headerOpts.center && (
+                    <div className="min-w-0 flex-1 overflow-hidden md:flex-none">
+                      {headerOpts.center}
+                    </div>
+                  )}
+                  {headerOpts.actions && (
+                    <div className="ml-auto flex shrink-0 items-center gap-2">
+                      {headerOpts.actions}
+                    </div>
+                  )}
+                </div>
+              )}
+            </header>
+          </div>
+        )}
+        <div
+          className={cn(
+            "flex flex-1 flex-col gap-4 p-4 md:gap-6 md:p-6 print:overflow-visible",
+            contentMaxWidth && cn("mx-auto w-full", contentMaxWidth),
+            contentClassName,
+          )}
+        >
+          {children}
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+
+/** แผง sidebar — แยกเพื่อใช้ useSidebar (ล้างคำค้นเมื่อยุบ ไม่ให้เมนูถูกกรองทั้งที่มองไม่เห็นช่องค้นหา) */
+function ShellSidebar({
+  brand,
+  nav,
+  searchable,
+  searchPlaceholder,
+  pin,
+  sidebarHeader,
+  sidebarFooter,
+  collapsible,
+}: Pick<
+  AppShellProps,
+  | "brand"
+  | "nav"
+  | "searchable"
+  | "searchPlaceholder"
+  | "pin"
+  | "sidebarHeader"
+  | "sidebarFooter"
+  | "collapsible"
+>) {
+  const { state, isMobile } = useSidebar();
+  const [query, setQuery] = useState("");
+  const collapsed = state === "collapsed" && !isMobile;
+  useEffect(() => {
+    if (collapsed) setQuery("");
+  }, [collapsed]);
+  const visibleNav = useMemo(() => searchNav(nav, query), [nav, query]);
+  const searching = query.trim().length > 0;
+
+  return (
+    <Sidebar collapsible={collapsible} className="print:hidden">
+      <SidebarHeader>
+        <AppBrand {...brand} />
+        {searchable && (
+          <div className="group-data-[collapsible=icon]:hidden">
+            <InputGroup className="h-8 bg-background shadow-none">
+              <InputGroupAddon>
+                <Search aria-hidden="true" />
+              </InputGroupAddon>
+              <InputGroupInput
+                name="sidebar-search"
+                aria-label={searchPlaceholder}
+                autoComplete="off"
+                placeholder={searchPlaceholder}
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+              />
+              {query && (
+                <InputGroupAddon align="inline-end">
+                  <InputGroupButton
+                    onClick={() => setQuery("")}
+                    aria-label="ล้างคำค้นหาเมนู"
+                    className="size-6 p-0 hover:bg-transparent"
+                  >
+                    <X aria-hidden="true" />
+                  </InputGroupButton>
+                </InputGroupAddon>
+              )}
+            </InputGroup>
+          </div>
+        )}
+        {sidebarHeader}
+      </SidebarHeader>
+      <SidebarContent>
+        <AppNav nav={visibleNav} pin={pin} forceOpen={searching} />
+      </SidebarContent>
+      {sidebarFooter && <SidebarFooter>{sidebarFooter}</SidebarFooter>}
+      {collapsible !== "none" && <SidebarRail />}
+    </Sidebar>
+  );
+}
+
+function isBreadcrumbOptions(value: unknown): value is HeaderBreadcrumbsProps {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !("$$typeof" in (value as object)) &&
+    !Array.isArray(value)
+  );
+}

package/src/components/app-shell/header-breadcrumbs.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "@suphark/ui/components/ui/breadcrumb";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { Fragment } from "react";
+
+export interface HeaderBreadcrumbsProps {
+  /** ชื่อแสดงของแต่ละ segment (`{ "po-tracking": "PO Tracking" }`) — ไม่พบ = ตัวแรกพิมพ์ใหญ่ แทน - ด้วยช่องว่าง */
+  labels?: Record<string, string>;
+  homeHref?: string;
+  homeLabel?: string;
+  /** ตัด segment นำหน้าออก เช่น `["console"]` เมื่อทุกหน้าอยู่ใต้ /console */
+  skip?: string[];
+  /** ซ่อน segment ที่ดูเหมือน id (ตัวเลข/uuid/cuid) */
+  hideIds?: boolean;
+}
+
+const ID_LIKE = /^(\d+|[0-9a-f]{8}-[0-9a-f-]{27}|c[a-z0-9]{20,}|[0-9a-z]{16,})$/i;
+
+function labelOf(segment: string, labels?: Record<string, string>) {
+  const known = labels?.[segment];
+  if (known) return known;
+  const decoded = decodeURIComponent(segment);
+  return decoded.charAt(0).toUpperCase() + decoded.slice(1).replace(/-/g, " ");
+}
+
+/** breadcrumb อัตโนมัติจาก pathname (ยกจาก supplychain HeaderBreadcrumbs) */
+export function HeaderBreadcrumbs({
+  labels,
+  homeHref = "/",
+  homeLabel = "Home",
+  skip = [],
+  hideIds = false,
+}: HeaderBreadcrumbsProps) {
+  const pathname = usePathname();
+  const all = pathname.split("/").filter(Boolean);
+  // segments ที่ยังคง href เต็ม แต่ไม่แสดงตัวที่อยู่ใน skip / เป็น id
+  const shown = all
+    .map((segment, index) => ({ segment, href: `/${all.slice(0, index + 1).join("/")}` }))
+    .filter(({ segment }) => !skip.includes(segment) && !(hideIds && ID_LIKE.test(segment)));
+
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem className="hidden md:block">
+          <BreadcrumbLink render={<Link href={homeHref} />}>{homeLabel}</BreadcrumbLink>
+        </BreadcrumbItem>
+        {shown.length > 0 && <BreadcrumbSeparator className="hidden md:block" />}
+        {shown.map(({ segment, href }, index) => {
+          const isLast = index === shown.length - 1;
+          const label = labelOf(segment, labels);
+          return (
+            <Fragment key={href}>
+              <BreadcrumbItem>
+                {isLast ? (
+                  <BreadcrumbPage className="max-w-[160px] truncate md:max-w-none">
+                    {label}
+                  </BreadcrumbPage>
+                ) : (
+                  <BreadcrumbLink render={<Link href={href} />}>{label}</BreadcrumbLink>
+                )}
+              </BreadcrumbItem>
+              {!isLast && <BreadcrumbSeparator className="hidden md:block" />}
+            </Fragment>
+          );
+        })}
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}

package/src/components/app-shell/index.ts

@@ -0,0 +1,14 @@
+export { AppBrand, type AppBrandProps } from "./app-brand";
+export { AppNav, AppNavGroupMenu, type AppNavPinProps } from "./app-nav";
+export { AppShell, type AppShellProps } from "./app-shell";
+export { HeaderBreadcrumbs, type HeaderBreadcrumbsProps } from "./header-breadcrumbs";
+export { NavLink } from "./nav-link";
+export {
+  type AppNavGroup,
+  type AppNavItem,
+  filterNav,
+  flattenNav,
+  isNavActive,
+  searchNav,
+} from "./types";
+export { UserMenu, type UserMenuProps, type UserMenuUser } from "./user-menu";

package/src/components/app-shell/nav-link.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { cn } from "@suphark/ui/lib/utils";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import type { ComponentProps, ReactNode } from "react";
+import { isNavActive } from "./types";
+
+/** ลิงก์ที่ไฮไลต์เมื่อ path ปัจจุบันอยู่ใต้ href (prefix match) — ยกจาก Pi Auth */
+export function NavLink({
+  href,
+  children,
+  exact = false,
+  className,
+  activeClassName = "bg-accent text-accent-foreground font-medium",
+  ...props
+}: Omit<ComponentProps<typeof Link>, "href"> & {
+  href: string;
+  children: ReactNode;
+  exact?: boolean;
+  activeClassName?: string;
+}) {
+  const pathname = usePathname();
+  const active = isNavActive(pathname, href, exact);
+  return (
+    <Link
+      href={href}
+      className={cn(className, active && activeClassName)}
+      aria-current={active ? "page" : undefined}
+      {...props}
+    >
+      {children}
+    </Link>
+  );
+}

package/src/components/app-shell/types.ts

@@ -0,0 +1,92 @@
+import type { CheckPermissionRequirement } from "@suphark/ui/lib/permission";
+import type { ReactNode } from "react";
+
+/**
+ * โมเดลเมนูของ AppShell — ใช้ร่วมกันทุกแอป
+ *
+ * `icon` เป็น ReactNode (เช่น `<UsersIcon />`) ไม่ใช่ component เพื่อให้ประกาศเมนูใน server component
+ * (layout.tsx) แล้วส่งเข้า client component ได้ (function ส่งข้าม boundary ไม่ได้)
+ */
+export interface AppNavItem {
+  title: string;
+  /** ไม่มี href = หัวกลุ่มย่อยที่กางออก (ต้องมี items) */
+  href?: string;
+  icon?: ReactNode;
+  /** เมนูย่อย (รองรับ 2 ชั้น: item → items) */
+  items?: AppNavItem[];
+  /** ไฮไลต์เฉพาะเมื่อ path ตรงทั้งหมด (ค่าเริ่มต้น: prefix match) */
+  exact?: boolean;
+  /** สิทธิ์ที่ต้องมีจึงเห็นเมนูนี้ — ตัดด้วย `filterNav` */
+  permission?: CheckPermissionRequirement;
+  /** ป้ายท้ายเมนู เช่นจำนวนงานค้าง */
+  badge?: ReactNode;
+  /** ฟีเจอร์ทดลอง — แสดงสีอำพัน + ไอคอนขวดทดลอง (ตาม supplychain) */
+  isLabs?: boolean;
+}
+
+export interface AppNavGroup {
+  /** หัวกลุ่ม (ไม่ใส่ = ไม่มีหัว) */
+  title?: string;
+  items: AppNavItem[];
+  permission?: CheckPermissionRequirement;
+}
+
+/**
+ * ตัดเมนูที่ผู้ใช้ไม่มีสิทธิ์ออกทุกชั้น — ไม่ให้กดแล้วเจอหน้า error (หน้าเองยังต้องตรวจสิทธิ์ซ้ำ)
+ * `can` = ตัวตรวจของแอป (เช่น `ctx.can`, หรือ `usePermissionChecker()` ฝั่ง client)
+ */
+export function filterNav(
+  nav: AppNavGroup[],
+  can: (permission: CheckPermissionRequirement) => boolean,
+): AppNavGroup[] {
+  const filterItems = (items: AppNavItem[]): AppNavItem[] =>
+    items
+      .filter((item) => !item.permission || can(item.permission))
+      .map((item) => (item.items ? { ...item, items: filterItems(item.items) } : item))
+      // กลุ่มย่อยที่ลูกโดนตัดหมดและตัวเองไม่มี href → ตัดทิ้ง
+      .filter((item) => item.href || (item.items && item.items.length > 0));
+
+  return nav
+    .filter((group) => !group.permission || can(group.permission))
+    .map((group) => ({ ...group, items: filterItems(group.items) }))
+    .filter((group) => group.items.length > 0);
+}
+
+/** true เมื่อ pathname อยู่ใต้ href (หรือตรงทั้งหมดเมื่อ exact) */
+export function isNavActive(pathname: string, href: string | undefined, exact = false): boolean {
+  if (!href || href === "#") return false;
+  if (exact || href === "/") return pathname === href;
+  return pathname === href || pathname.startsWith(`${href}/`);
+}
+
+/** กรองเมนูตามคำค้น (ช่องค้นหาเมนูใน sidebar) — เก็บ parent ไว้ถ้าลูกตรง */
+export function searchNav(nav: AppNavGroup[], query: string): AppNavGroup[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return nav;
+  const filterItems = (items: AppNavItem[]): AppNavItem[] =>
+    items
+      .map((item) => {
+        if (item.title.toLowerCase().includes(q)) return item;
+        const children = item.items ? filterItems(item.items) : [];
+        return children.length > 0 ? { ...item, items: children } : null;
+      })
+      .filter((item): item is AppNavItem => item !== null);
+  return nav
+    .map((group) => ({ ...group, items: filterItems(group.items) }))
+    .filter((group) => group.items.length > 0);
+}
+
+/** รายการเมนูทั้งหมดแบบแบน (สำหรับ command palette / pinned menus) */
+export function flattenNav(
+  nav: AppNavGroup[],
+): Array<AppNavItem & { href: string; group?: string }> {
+  const out: Array<AppNavItem & { href: string; group?: string }> = [];
+  const walk = (items: AppNavItem[], group?: string) => {
+    for (const item of items) {
+      if (item.href) out.push({ ...item, href: item.href, group });
+      if (item.items) walk(item.items, group);
+    }
+  };
+  for (const g of nav) walk(g.items, g.title);
+  return out;
+}

package/src/components/app-shell/user-menu.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { Initials } from "@suphark/ui/components/shared/initials";
+import { Button } from "@suphark/ui/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@suphark/ui/components/ui/dropdown-menu";
+import { cn } from "@suphark/ui/lib/utils";
+import { ChevronsUpDown, LogOut } from "lucide-react";
+import { type ReactNode, useTransition } from "react";
+
+export interface UserMenuUser {
+  name: string;
+  email?: string | null;
+  /** URL รูป */
+  image?: string | null;
+  /** บรรทัดรอง เช่น ตำแหน่ง · องค์กร */
+  description?: ReactNode;
+}
+
+export interface UserMenuProps {
+  user: UserMenuUser;
+  /**
+   * รายการเมนู (DropdownMenuItem / DropdownMenuGroup / ThemeMenuItems …) — วางระหว่างหัวกับปุ่มออกจากระบบ
+   * แอปเป็นคนใส่เอง เช่น บัญชีผู้ใช้, การแจ้งเตือน, ธีม, สลับภาษา
+   */
+  children?: ReactNode;
+  /** ไม่ส่ง = ไม่มีปุ่มออกจากระบบ */
+  onSignOut?: () => void | Promise<void>;
+  signOutLabel?: ReactNode;
+  /**
+   * `sidebar` = ปุ่มกว้างเต็ม footer ของ sidebar (Pi Auth) · `header` = ปุ่มกะทัดรัดใน header (supplychain)
+   */
+  variant?: "sidebar" | "header";
+  align?: "start" | "end";
+  className?: string;
+}
+
+/** เมนูผู้ใช้ (ยกจาก supplychain NavUser + Pi Auth UserMenu) */
+export function UserMenu({
+  user,
+  children,
+  onSignOut,
+  signOutLabel = "ออกจากระบบ",
+  variant = "sidebar",
+  align = variant === "header" ? "end" : "start",
+  className,
+}: UserMenuProps) {
+  const [pending, start] = useTransition();
+  const description = user.description ?? user.email;
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <Button
+            variant="ghost"
+            aria-label={`เปิดเมนูผู้ใช้ ${user.name}`}
+            className={cn(
+              variant === "sidebar"
+                ? "h-auto w-full justify-start gap-2.5 px-2 py-2 text-left group-data-[collapsible=icon]:size-8 group-data-[collapsible=icon]:p-0"
+                : "h-9 min-w-0 gap-2 px-1.5 data-[state=open]:bg-accent sm:px-2",
+              className,
+            )}
+          />
+        }
+      >
+        <Initials name={user.name} src={user.image} size="sm" />
+        <span
+          className={cn(
+            "min-w-0 flex-1 flex-col text-left leading-tight",
+            variant === "sidebar" ? "flex group-data-[collapsible=icon]:hidden" : "hidden xl:flex",
+          )}
+        >
+          <span className="truncate font-medium text-sm">{user.name}</span>
+          {description && (
+            <span className="truncate text-muted-foreground text-xs">{description}</span>
+          )}
+        </span>
+        <ChevronsUpDown
+          aria-hidden="true"
+          className={cn(
+            "text-muted-foreground",
+            variant === "sidebar" ? "group-data-[collapsible=icon]:hidden" : "hidden xl:block",
+          )}
+        />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align={align}
+        side={variant === "header" ? "bottom" : undefined}
+        sideOffset={variant === "header" ? 8 : 4}
+        className="min-w-60 rounded-lg"
+      >
+        <DropdownMenuGroup>
+          <DropdownMenuLabel className="p-0 font-normal">
+            <div className="flex min-w-0 items-center gap-2 px-2 py-2 text-left text-sm">
+              <Initials name={user.name} src={user.image} size="sm" />
+              <div className="grid min-w-0 flex-1 leading-tight">
+                <span className="truncate font-medium">{user.name}</span>
+                {user.description && (
+                  <span className="truncate text-muted-foreground text-xs">{user.description}</span>
+                )}
+                {user.email && (
+                  <span className="truncate text-muted-foreground text-xs">{user.email}</span>
+                )}
+              </div>
+            </div>
+          </DropdownMenuLabel>
+        </DropdownMenuGroup>
+        {children && (
+          <>
+            <DropdownMenuSeparator />
+            {children}
+          </>
+        )}
+        {onSignOut && (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem disabled={pending} onClick={() => start(() => onSignOut())}>
+              <LogOut aria-hidden="true" />
+              {signOutLabel}
+            </DropdownMenuItem>
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/index.ts

@@ -9,6 +9,8 @@
  * `chart` (recharts) ไม่อยู่ใน barrel: import ตรง `@suphark/ui/components/ui/chart` เมื่อแอปติดตั้ง recharts เอง
  */
 
+// sonner: `toast()` คู่กับ <Toaster /> — แอปไม่ต้องติดตั้ง sonner เอง
+export { toast } from "sonner";
 export * from "./components/shared/button";
 export { ClientRedirect } from "./components/shared/client-redirect";
 export { Combobox } from "./components/shared/combobox";
@@ -131,7 +133,6 @@ export * from "./components/ui/textarea";
 export * from "./components/ui/toggle";
 export * from "./components/ui/toggle-group";
 export * from "./components/ui/tooltip";
-
 // ---------- lib / hooks ----------
 export { useCopyToClipboard } from "./hooks/use-copy-to-clipboard";
 export { useIsMobile } from "./hooks/use-mobile";

package/src/next.ts

@@ -2,6 +2,9 @@
  * @suphark/ui/next — component ที่ต้องรันใน Next.js (ใช้ next/navigation หรือ next/link)
  * แยกจาก barrel หลักเพื่อให้ `@suphark/ui` ใช้ได้ในสภาพแวดล้อมที่ไม่มี next (vitest, Vite, Storybook)
  */
+
+// ---------- app shell (sidebar + header + เนื้อหา) ----------
+export * from "./components/app-shell";
 export { LinkButton, type LinkButtonProps } from "./components/shared/button/base/link-button";
 export { RefreshButton } from "./components/shared/button/refresh-button";
 export { FormDialog } from "./components/shared/form-dialog";