@comitor/ui 0.1.0

package/dist/components/composite/letter-avatar.js

@@ -0,0 +1,66 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+import { getVietnameseInitials, hashString } from "./text-utils.js";
+const LETTER_AVATAR_TONES = [
+  "bg-gold-100 text-gold-600 dark:bg-gold-500/30 dark:text-gold-100",
+  "bg-teal/15 text-teal",
+  "bg-green/15 text-green",
+  "bg-red/15 text-red",
+  "bg-yellow/25 text-gold-500 dark:bg-yellow/20 dark:text-yellow",
+  "bg-chart-3/15 text-chart-3",
+  "bg-ash-100 text-ash-700 dark:bg-ash-500/25 dark:text-ash-100",
+  "bg-ink/10 text-ink-soft dark:bg-paper/15 dark:text-paper"
+];
+const sizeClasses = {
+  xs: "size-6 text-[10px]",
+  sm: "size-7 text-xs",
+  md: "size-9 text-sm",
+  lg: "size-11 text-base",
+  xl: "size-14 text-lg"
+};
+function getLetterAvatarTone(name) {
+  const tones = LETTER_AVATAR_TONES;
+  return tones[hashString(name.trim().toLocaleLowerCase("vi-VN")) % tones.length] ?? tones[0];
+}
+function LetterAvatar({
+  name,
+  src,
+  size = "md",
+  square = false,
+  toneClassName,
+  className,
+  ...props
+}) {
+  const tone = toneClassName ?? getLetterAvatarTone(name);
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      "data-slot": "letter-avatar",
+      title: name,
+      className: cn(
+        "relative inline-flex shrink-0 select-none items-center justify-center overflow-hidden font-medium",
+        square ? "rounded-md" : "rounded-full",
+        sizeClasses[size],
+        !src && tone,
+        className
+      ),
+      ...props,
+      children: [
+        src ? (
+          // Không dùng next/image: entry "." phải chạy cả ngoài Next (Vite, Storybook, test).
+          // App muốn tối ưu ảnh thì truyền URL đã qua CDN/loader của mình.
+          // `alt=""`: tên đã nằm ở `sr-only` bên dưới — để alt={name} nữa là đọc tên hai lần.
+          // biome-ignore lint/performance/noImgElement: package dùng chung không phụ thuộc next/*
+          /* @__PURE__ */ jsx("img", { src, alt: "", className: "size-full object-cover", loading: "lazy", decoding: "async" })
+        ) : /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: getVietnameseInitials(name) }),
+        /* @__PURE__ */ jsx("span", { className: "sr-only", children: name })
+      ]
+    }
+  );
+}
+export {
+  LETTER_AVATAR_TONES,
+  LetterAvatar,
+  getLetterAvatarTone
+};
+//# sourceMappingURL=letter-avatar.js.map

package/dist/components/composite/letter-avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/composite/letter-avatar.tsx"],"sourcesContent":["import type { ComponentProps } from \"react\";\nimport { cn } from \"../../lib/cn.js\";\nimport { getVietnameseInitials, hashString } from \"./text-utils.js\";\n\nexport type LetterAvatarSize = \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\";\n\n/**\n * 8 tone màu deterministic — TẤT CẢ là class token tĩnh.\n *\n * Vì sao không sinh `bg-${color}-100`: Tailwind quét tĩnh, class ghép chuỗi lúc chạy sẽ không\n * có mặt trong CSS của app → avatar mất nền. Vì sao không dùng hex inline: mất dark mode.\n * Mỗi tone đã chọn cặp nền/chữ đạt tương phản ở cả hai theme.\n *\n * ⚠ Đây là NGUỒN SỰ THẬT DUY NHẤT cho màu avatar chữ cái của cả package: tầng shell\n * (`shell/utils.ts` → `getAvatarToneClass`) gọi lại `getLetterAvatarTone` chứ không giữ\n * bảng tone riêng. Đừng dựng bảng thứ hai — cùng một người mà ra hai màu trên cùng một\n * trang là lỗi đã từng xảy ra ở 0.1.0.\n */\nexport const LETTER_AVATAR_TONES = [\n  \"bg-gold-100 text-gold-600 dark:bg-gold-500/30 dark:text-gold-100\",\n  \"bg-teal/15 text-teal\",\n  \"bg-green/15 text-green\",\n  \"bg-red/15 text-red\",\n  \"bg-yellow/25 text-gold-500 dark:bg-yellow/20 dark:text-yellow\",\n  \"bg-chart-3/15 text-chart-3\",\n  \"bg-ash-100 text-ash-700 dark:bg-ash-500/25 dark:text-ash-100\",\n  \"bg-ink/10 text-ink-soft dark:bg-paper/15 dark:text-paper\"\n] as const;\n\nconst sizeClasses: Record<LetterAvatarSize, string> = {\n  xs: \"size-6 text-[10px]\",\n  sm: \"size-7 text-xs\",\n  md: \"size-9 text-sm\",\n  lg: \"size-11 text-base\",\n  xl: \"size-14 text-lg\"\n};\n\n/**\n * Tone màu ổn định theo tên — cùng một người luôn ra cùng màu ở mọi app Comitor.\n *\n * SEED là TÊN (đã trim + hạ chữ thường theo locale vi-VN), không phải email/slug: mọi nơi\n * hiển thị avatar đều chắc chắn có `name`, còn email/slug thì không — lấy khoá khác nhau ở\n * từng chỗ là cách nhanh nhất để cùng một người ra hai màu.\n */\nexport function getLetterAvatarTone(name: string): string {\n  const tones = LETTER_AVATAR_TONES;\n  return tones[hashString(name.trim().toLocaleLowerCase(\"vi-VN\")) % tones.length] ?? tones[0];\n}\n\nexport interface LetterAvatarProps extends Omit<ComponentProps<\"span\">, \"children\"> {\n  /** Họ tên đầy đủ — dùng cho cả initials lẫn màu */\n  name: string;\n  /** Có ảnh thì hiện ảnh, không thì rơi về initials */\n  src?: string | null;\n  size?: LetterAvatarSize;\n  /** Bo vuông (dùng cho workspace/app) thay vì tròn (dùng cho người) */\n  square?: boolean;\n  /** Ghi đè tone (chuỗi class token) — vd tô theo màu app thay vì theo tên */\n  toneClassName?: string;\n}\n\n/**\n * Avatar chữ cái: ảnh nếu có, không thì initials kiểu Việt (chữ đầu HỌ + chữ đầu TÊN) trên nền\n * màu suy ra từ tên.\n *\n * Không dùng primitive `Avatar` (Radix) một cách cố ý: Radix Avatar là client component vì phải\n * theo dõi trạng thái tải ảnh; ở danh sách 200 dòng thì đó là 200 island vô ích. Bản này tĩnh\n * hoàn toàn → render thẳng ở server.\n */\nexport function LetterAvatar({\n  name,\n  src,\n  size = \"md\",\n  square = false,\n  toneClassName,\n  className,\n  ...props\n}: LetterAvatarProps) {\n  const tone = toneClassName ?? getLetterAvatarTone(name);\n\n  return (\n    <span\n      data-slot=\"letter-avatar\"\n      title={name}\n      className={cn(\n        \"relative inline-flex shrink-0 select-none items-center justify-center overflow-hidden font-medium\",\n        square ? \"rounded-md\" : \"rounded-full\",\n        sizeClasses[size],\n        !src && tone,\n        className\n      )}\n      {...props}\n    >\n      {src ? (\n        // Không dùng next/image: entry \".\" phải chạy cả ngoài Next (Vite, Storybook, test).\n        // App muốn tối ưu ảnh thì truyền URL đã qua CDN/loader của mình.\n        // `alt=\"\"`: tên đã nằm ở `sr-only` bên dưới — để alt={name} nữa là đọc tên hai lần.\n        // biome-ignore lint/performance/noImgElement: package dùng chung không phụ thuộc next/*\n        <img src={src} alt=\"\" className=\"size-full object-cover\" loading=\"lazy\" decoding=\"async\" />\n      ) : (\n        <span aria-hidden=\"true\">{getVietnameseInitials(name)}</span>\n      )}\n      {/* Tên cho trình đọc màn hình ở MỌI nhánh: nhánh initials vốn `aria-hidden` (chữ \"NT\"\n          đọc lên vô nghĩa), thiếu dòng này thì avatar không ảnh là một ô màu câm — và khi\n          avatar nằm trong một trigger (AvatarGroup) thì chính nó là tên của trigger đó. */}\n      <span className=\"sr-only\">{name}</span>\n    </span>\n  );\n}\n"],"mappings":"AAiFI,SAiBI,KAjBJ;AAhFJ,SAAS,UAAU;AACnB,SAAS,uBAAuB,kBAAkB;AAgB3C,MAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,MAAM,cAAgD;AAAA,EACpD,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AASO,SAAS,oBAAoB,MAAsB;AACxD,QAAM,QAAQ;AACd,SAAO,MAAM,WAAW,KAAK,KAAK,EAAE,kBAAkB,OAAO,CAAC,IAAI,MAAM,MAAM,KAAK,MAAM,CAAC;AAC5F;AAsBO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AAAA,EACA,OAAO;AAAA,EACP,SAAS;AAAA,EACT;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAsB;AACpB,QAAM,OAAO,iBAAiB,oBAAoB,IAAI;AAEtD,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,OAAO;AAAA,MACP,WAAW;AAAA,QACT;AAAA,QACA,SAAS,eAAe;AAAA,QACxB,YAAY,IAAI;AAAA,QAChB,CAAC,OAAO;AAAA,QACR;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAKC,oBAAC,SAAI,KAAU,KAAI,IAAG,WAAU,0BAAyB,SAAQ,QAAO,UAAS,SAAQ;AAAA,YAEzF,oBAAC,UAAK,eAAY,QAAQ,gCAAsB,IAAI,GAAE;AAAA,QAKxD,oBAAC,UAAK,WAAU,WAAW,gBAAK;AAAA;AAAA;AAAA,EAClC;AAEJ;","names":[]}

package/dist/components/composite/page-container.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { ComponentProps } from 'react';
+
+type PageContainerWidth = "sm" | "md" | "lg" | "full";
+interface PageContainerProps extends ComponentProps<"div"> {
+    /**
+     * Bề rộng nội dung tối đa:
+     * `sm` 42rem (trang cài đặt, form một cột) · `md` 64rem (mặc định, trang chi tiết)
+     * `lg` 90rem (bảng nhiều cột) · `full` không giới hạn (bảng full-bleed, kanban).
+     */
+    width?: PageContainerWidth;
+    /** Bỏ padding dọc — dùng khi trang tự quản khoảng cách (vd kanban cuộn ngang) */
+    flush?: boolean;
+    /** Đổi thẻ bọc (mặc định `div`; đặt "main" khi container là vùng nội dung chính) */
+    as?: "div" | "main" | "section";
+}
+/**
+ * Khung nội dung chuẩn của trang: căn giữa, giới hạn bề rộng, padding theo breakpoint.
+ *
+ * Vì sao cần: nếu mỗi trang tự viết `px-4 md:px-6 max-w-…` thì lề trái của Tasks và CRM
+ * sẽ lệch nhau vài px — lỗi rất khó thấy nhưng làm hệ sinh thái trông rời rạc. Tĩnh → RSC-safe.
+ */
+declare function PageContainer({ width, flush, as, className, ...props }: PageContainerProps): React.JSX.Element;
+
+export { PageContainer, type PageContainerProps, type PageContainerWidth };

package/dist/components/composite/page-container.js

@@ -0,0 +1,23 @@
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+const widthClasses = {
+  sm: "max-w-2xl",
+  md: "max-w-5xl",
+  lg: "max-w-[90rem]",
+  full: "max-w-none"
+};
+function PageContainer({ width = "md", flush = false, as = "div", className, ...props }) {
+  const Comp = as;
+  return /* @__PURE__ */ jsx(
+    Comp,
+    {
+      "data-slot": "page-container",
+      className: cn("mx-auto w-full px-4 md:px-6", !flush && "py-4 md:py-6", widthClasses[width], className),
+      ...props
+    }
+  );
+}
+export {
+  PageContainer
+};
+//# sourceMappingURL=page-container.js.map

package/dist/components/composite/page-container.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/composite/page-container.tsx"],"sourcesContent":["import type { ComponentProps } from \"react\";\nimport { cn } from \"../../lib/cn.js\";\n\nexport type PageContainerWidth = \"sm\" | \"md\" | \"lg\" | \"full\";\n\nexport interface PageContainerProps extends ComponentProps<\"div\"> {\n  /**\n   * Bề rộng nội dung tối đa:\n   * `sm` 42rem (trang cài đặt, form một cột) · `md` 64rem (mặc định, trang chi tiết)\n   * `lg` 90rem (bảng nhiều cột) · `full` không giới hạn (bảng full-bleed, kanban).\n   */\n  width?: PageContainerWidth;\n  /** Bỏ padding dọc — dùng khi trang tự quản khoảng cách (vd kanban cuộn ngang) */\n  flush?: boolean;\n  /** Đổi thẻ bọc (mặc định `div`; đặt \"main\" khi container là vùng nội dung chính) */\n  as?: \"div\" | \"main\" | \"section\";\n}\n\nconst widthClasses: Record<PageContainerWidth, string> = {\n  sm: \"max-w-2xl\",\n  md: \"max-w-5xl\",\n  lg: \"max-w-[90rem]\",\n  full: \"max-w-none\"\n};\n\n/**\n * Khung nội dung chuẩn của trang: căn giữa, giới hạn bề rộng, padding theo breakpoint.\n *\n * Vì sao cần: nếu mỗi trang tự viết `px-4 md:px-6 max-w-…` thì lề trái của Tasks và CRM\n * sẽ lệch nhau vài px — lỗi rất khó thấy nhưng làm hệ sinh thái trông rời rạc. Tĩnh → RSC-safe.\n */\nexport function PageContainer({ width = \"md\", flush = false, as = \"div\", className, ...props }: PageContainerProps) {\n  const Comp = as;\n\n  return (\n    <Comp\n      data-slot=\"page-container\"\n      className={cn(\"mx-auto w-full px-4 md:px-6\", !flush && \"py-4 md:py-6\", widthClasses[width], className)}\n      {...props}\n    />\n  );\n}\n"],"mappings":"AAmCI;AAlCJ,SAAS,UAAU;AAiBnB,MAAM,eAAmD;AAAA,EACvD,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,MAAM;AACR;AAQO,SAAS,cAAc,EAAE,QAAQ,MAAM,QAAQ,OAAO,KAAK,OAAO,WAAW,GAAG,MAAM,GAAuB;AAClH,QAAM,OAAO;AAEb,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,WAAW,GAAG,+BAA+B,CAAC,SAAS,gBAAgB,aAAa,KAAK,GAAG,SAAS;AAAA,MACpG,GAAG;AAAA;AAAA,EACN;AAEJ;","names":[]}

package/dist/components/composite/page-header.d.ts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { ComponentProps, ReactNode, ComponentType } from 'react';
+import { IconComponent } from './empty-state.js';
+
+/** Props tối thiểu của component link app tiêm vào (vd `next/link`). */
+interface PageHeaderLinkProps {
+    href: string;
+    className?: string;
+    children: ReactNode;
+}
+interface PageHeaderBreadcrumbItem {
+    label: string;
+    /** Không có href → mục tĩnh (thường là mục cuối = trang hiện tại) */
+    href?: string;
+}
+interface PageHeaderProps extends Omit<ComponentProps<"header">, "title"> {
+    title: ReactNode;
+    description?: ReactNode;
+    /** Icon nhỏ đứng trước tiêu đề (vd icon của app/khu vực) */
+    icon?: IconComponent;
+    /** Đường dẫn phân cấp; mục cuối luôn render dạng "trang hiện tại" (không bấm được) */
+    breadcrumb?: PageHeaderBreadcrumbItem[];
+    /**
+     * Component link cho breadcrumb — mặc định thẻ `<a>` thường.
+     *
+     * Vì sao nhận qua prop thay vì import `next/link`: entry "." của package phải chạy được cả
+     * ngoài Next (Vite, Storybook, test). Đụng `next/*` ở đây là vỡ resolve ngay khi app chỉ
+     * `import { Button }`.
+     */
+    LinkComponent?: ComponentType<PageHeaderLinkProps>;
+    /** Slot hành động bên phải (nút Tạo mới, menu …) */
+    actions?: ReactNode;
+    /** Hàng phụ dưới tiêu đề: tabs, thanh lọc, chip trạng thái… */
+    children?: ReactNode;
+    /** Dính đỉnh vùng cuộn (danh sách dài) */
+    sticky?: boolean;
+    /** Bỏ đường kẻ dưới header */
+    borderless?: boolean;
+}
+/**
+ * Header trang chuẩn: breadcrumb + tiêu đề + mô tả + slot hành động (+ hàng phụ).
+ *
+ * Nhận breadcrumb qua props, KHÔNG đọc từ context của shell: khi PageHeader phụ thuộc
+ * ShellContext thì mọi trang không nằm trong shell (trang in ấn, trang lỗi, dialog toàn
+ * màn hình) đều nổ. Tĩnh hoàn toàn → RSC-safe.
+ */
+declare function PageHeader({ title, description, icon: Icon, breadcrumb, LinkComponent, actions, children, sticky, borderless, className, ...props }: PageHeaderProps): React.JSX.Element;
+
+export { PageHeader, type PageHeaderBreadcrumbItem, type PageHeaderLinkProps, type PageHeaderProps };

package/dist/components/composite/page-header.js

@@ -0,0 +1,75 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { cn } from "../../lib/cn.js";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator
+} from "../ui/breadcrumb.js";
+function DefaultLink({ href, className, children }) {
+  return /* @__PURE__ */ jsx("a", { href, className, children });
+}
+function PageHeader({
+  title,
+  description,
+  icon: Icon,
+  breadcrumb = [],
+  LinkComponent = DefaultLink,
+  actions,
+  children,
+  sticky = false,
+  borderless = false,
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs(
+    "header",
+    {
+      "data-slot": "page-header",
+      className: cn(
+        "w-full bg-background px-4 pt-4 md:px-6",
+        !borderless && "border-b border-border pb-4",
+        sticky && "sticky top-0 z-20 backdrop-blur supports-[backdrop-filter]:bg-background/80",
+        className
+      ),
+      ...props,
+      children: [
+        breadcrumb.length > 0 && /* @__PURE__ */ jsx(Breadcrumb, { className: "mb-2", children: /* @__PURE__ */ jsx(BreadcrumbList, { children: breadcrumb.map((item, index) => {
+          const isLast = index === breadcrumb.length - 1;
+          return (
+            // biome-ignore lint/suspicious/noArrayIndexKey: breadcrumb là danh sách vị trí, nhãn có thể trùng giữa các cấp
+            /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(BreadcrumbItem, { children: isLast || !item.href ? /* @__PURE__ */ jsx(BreadcrumbPage, { children: item.label }) : /* @__PURE__ */ jsx(BreadcrumbLink, { asChild: true, children: /* @__PURE__ */ jsx(LinkComponent, { href: item.href, children: item.label }) }) }),
+              !isLast && /* @__PURE__ */ jsx(BreadcrumbSeparator, {})
+            ] }, `${index}-${item.label}`)
+          );
+        }) }) }),
+        /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [
+          /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 items-start gap-3", children: [
+            Icon && /* @__PURE__ */ jsx(
+              "span",
+              {
+                "aria-hidden": "true",
+                className: "mt-0.5 flex size-9 shrink-0 items-center justify-center rounded-md bg-app-accent/10 text-foreground",
+                children: /* @__PURE__ */ jsx(Icon, { className: "size-5" })
+              }
+            ),
+            /* @__PURE__ */ jsxs("div", { className: "min-w-0", children: [
+              /* @__PURE__ */ jsx("h1", { className: "truncate text-xl font-semibold tracking-tight text-foreground md:text-2xl", children: title }),
+              description && /* @__PURE__ */ jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: description })
+            ] })
+          ] }),
+          actions && /* @__PURE__ */ jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })
+        ] }),
+        children && /* @__PURE__ */ jsx("div", { className: "mt-3", children })
+      ]
+    }
+  );
+}
+export {
+  PageHeader
+};
+//# sourceMappingURL=page-header.js.map

package/dist/components/composite/page-header.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/composite/page-header.tsx"],"sourcesContent":["import type { ComponentProps, ComponentType, ReactNode } from \"react\";\nimport { Fragment } from \"react\";\nimport { cn } from \"../../lib/cn.js\";\nimport {\n  Breadcrumb,\n  BreadcrumbItem,\n  BreadcrumbLink,\n  BreadcrumbList,\n  BreadcrumbPage,\n  BreadcrumbSeparator\n} from \"../ui/breadcrumb.js\";\nimport type { IconComponent } from \"./empty-state.js\";\n\n/** Props tối thiểu của component link app tiêm vào (vd `next/link`). */\nexport interface PageHeaderLinkProps {\n  href: string;\n  className?: string;\n  children: ReactNode;\n}\n\nexport interface PageHeaderBreadcrumbItem {\n  label: string;\n  /** Không có href → mục tĩnh (thường là mục cuối = trang hiện tại) */\n  href?: string;\n}\n\nexport interface PageHeaderProps extends Omit<ComponentProps<\"header\">, \"title\"> {\n  title: ReactNode;\n  description?: ReactNode;\n  /** Icon nhỏ đứng trước tiêu đề (vd icon của app/khu vực) */\n  icon?: IconComponent;\n  /** Đường dẫn phân cấp; mục cuối luôn render dạng \"trang hiện tại\" (không bấm được) */\n  breadcrumb?: PageHeaderBreadcrumbItem[];\n  /**\n   * Component link cho breadcrumb — mặc định thẻ `<a>` thường.\n   *\n   * Vì sao nhận qua prop thay vì import `next/link`: entry \".\" của package phải chạy được cả\n   * ngoài Next (Vite, Storybook, test). Đụng `next/*` ở đây là vỡ resolve ngay khi app chỉ\n   * `import { Button }`.\n   */\n  LinkComponent?: ComponentType<PageHeaderLinkProps>;\n  /** Slot hành động bên phải (nút Tạo mới, menu …) */\n  actions?: ReactNode;\n  /** Hàng phụ dưới tiêu đề: tabs, thanh lọc, chip trạng thái… */\n  children?: ReactNode;\n  /** Dính đỉnh vùng cuộn (danh sách dài) */\n  sticky?: boolean;\n  /** Bỏ đường kẻ dưới header */\n  borderless?: boolean;\n}\n\nfunction DefaultLink({ href, className, children }: PageHeaderLinkProps) {\n  return (\n    <a href={href} className={className}>\n      {children}\n    </a>\n  );\n}\n\n/**\n * Header trang chuẩn: breadcrumb + tiêu đề + mô tả + slot hành động (+ hàng phụ).\n *\n * Nhận breadcrumb qua props, KHÔNG đọc từ context của shell: khi PageHeader phụ thuộc\n * ShellContext thì mọi trang không nằm trong shell (trang in ấn, trang lỗi, dialog toàn\n * màn hình) đều nổ. Tĩnh hoàn toàn → RSC-safe.\n */\nexport function PageHeader({\n  title,\n  description,\n  icon: Icon,\n  breadcrumb = [],\n  LinkComponent = DefaultLink,\n  actions,\n  children,\n  sticky = false,\n  borderless = false,\n  className,\n  ...props\n}: PageHeaderProps) {\n  return (\n    <header\n      data-slot=\"page-header\"\n      className={cn(\n        \"w-full bg-background px-4 pt-4 md:px-6\",\n        !borderless && \"border-b border-border pb-4\",\n        sticky && \"sticky top-0 z-20 backdrop-blur supports-[backdrop-filter]:bg-background/80\",\n        className\n      )}\n      {...props}\n    >\n      {breadcrumb.length > 0 && (\n        <Breadcrumb className=\"mb-2\">\n          <BreadcrumbList>\n            {breadcrumb.map((item, index) => {\n              const isLast = index === breadcrumb.length - 1;\n              return (\n                // biome-ignore lint/suspicious/noArrayIndexKey: breadcrumb là danh sách vị trí, nhãn có thể trùng giữa các cấp\n                <Fragment key={`${index}-${item.label}`}>\n                  <BreadcrumbItem>\n                    {isLast || !item.href ? (\n                      <BreadcrumbPage>{item.label}</BreadcrumbPage>\n                    ) : (\n                      <BreadcrumbLink asChild>\n                        <LinkComponent href={item.href}>{item.label}</LinkComponent>\n                      </BreadcrumbLink>\n                    )}\n                  </BreadcrumbItem>\n                  {!isLast && <BreadcrumbSeparator />}\n                </Fragment>\n              );\n            })}\n          </BreadcrumbList>\n        </Breadcrumb>\n      )}\n\n      <div className=\"flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between\">\n        <div className=\"flex min-w-0 items-start gap-3\">\n          {Icon && (\n            <span\n              aria-hidden=\"true\"\n              className=\"mt-0.5 flex size-9 shrink-0 items-center justify-center rounded-md bg-app-accent/10 text-foreground\"\n            >\n              <Icon className=\"size-5\" />\n            </span>\n          )}\n          <div className=\"min-w-0\">\n            <h1 className=\"truncate text-xl font-semibold tracking-tight text-foreground md:text-2xl\">{title}</h1>\n            {description && <p className=\"mt-1 text-sm text-muted-foreground\">{description}</p>}\n          </div>\n        </div>\n        {actions && <div className=\"flex shrink-0 flex-wrap items-center gap-2\">{actions}</div>}\n      </div>\n\n      {children && <div className=\"mt-3\">{children}</div>}\n    </header>\n  );\n}\n"],"mappings":"AAqDI,cA4CY,YA5CZ;AApDJ,SAAS,gBAAgB;AACzB,SAAS,UAAU;AACnB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAyCP,SAAS,YAAY,EAAE,MAAM,WAAW,SAAS,GAAwB;AACvE,SACE,oBAAC,OAAE,MAAY,WACZ,UACH;AAEJ;AASO,SAAS,WAAW;AAAA,EACzB;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,aAAa,CAAC;AAAA,EACd,gBAAgB;AAAA,EAChB;AAAA,EACA;AAAA,EACA,SAAS;AAAA,EACT,aAAa;AAAA,EACb;AAAA,EACA,GAAG;AACL,GAAoB;AAClB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,WAAW;AAAA,QACT;AAAA,QACA,CAAC,cAAc;AAAA,QACf,UAAU;AAAA,QACV;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA,mBAAW,SAAS,KACnB,oBAAC,cAAW,WAAU,QACpB,8BAAC,kBACE,qBAAW,IAAI,CAAC,MAAM,UAAU;AAC/B,gBAAM,SAAS,UAAU,WAAW,SAAS;AAC7C;AAAA;AAAA,YAEE,qBAAC,YACC;AAAA,kCAAC,kBACE,oBAAU,CAAC,KAAK,OACf,oBAAC,kBAAgB,eAAK,OAAM,IAE5B,oBAAC,kBAAe,SAAO,MACrB,8BAAC,iBAAc,MAAM,KAAK,MAAO,eAAK,OAAM,GAC9C,GAEJ;AAAA,cACC,CAAC,UAAU,oBAAC,uBAAoB;AAAA,iBAVpB,GAAG,KAAK,IAAI,KAAK,KAAK,EAWrC;AAAA;AAAA,QAEJ,CAAC,GACH,GACF;AAAA,QAGF,qBAAC,SAAI,WAAU,qEACb;AAAA,+BAAC,SAAI,WAAU,kCACZ;AAAA,oBACC;AAAA,cAAC;AAAA;AAAA,gBACC,eAAY;AAAA,gBACZ,WAAU;AAAA,gBAEV,8BAAC,QAAK,WAAU,UAAS;AAAA;AAAA,YAC3B;AAAA,YAEF,qBAAC,SAAI,WAAU,WACb;AAAA,kCAAC,QAAG,WAAU,6EAA6E,iBAAM;AAAA,cAChG,eAAe,oBAAC,OAAE,WAAU,sCAAsC,uBAAY;AAAA,eACjF;AAAA,aACF;AAAA,UACC,WAAW,oBAAC,SAAI,WAAU,8CAA8C,mBAAQ;AAAA,WACnF;AAAA,QAEC,YAAY,oBAAC,SAAI,WAAU,QAAQ,UAAS;AAAA;AAAA;AAAA,EAC/C;AAEJ;","names":[]}

package/dist/components/composite/relative-time.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { ComponentProps } from 'react';
+
+interface RelativeTimeProps extends Omit<ComponentProps<"time">, "dateTime" | "children"> {
+    /** Thời điểm cần hiển thị: Date, ISO string hoặc epoch ms */
+    value: Date | string | number;
+    /** Thêm hậu tố "trước"/"nữa" (mặc định true) */
+    addSuffix?: boolean;
+    /** Chu kỳ tự cập nhật (ms). 0 = không tự cập nhật. Mặc định 60_000. */
+    updateIntervalMs?: number;
+    /** Định dạng của tooltip `title` (mặc định "HH:mm 'ngày' dd/MM/yyyy") */
+    titleFormat?: string;
+    /** Nội dung thay thế khi `value` không hợp lệ */
+    fallback?: string;
+}
+/**
+ * Thời gian tương đối kiểu "3 phút trước", tự cập nhật theo chu kỳ.
+ *
+ * Dùng `formatDistanceToNowStrict` (không phải bản thường): bản thường làm tròn kiểu "khoảng 1
+ * tháng" cho mọi thứ từ 26 ngày đến 45 ngày — trong danh sách công việc thì "26 ngày trước" và
+ * "45 ngày trước" là hai câu chuyện khác hẳn nhau.
+ *
+ * `title` luôn giữ mốc thời gian tuyệt đối để người dùng rà chuột là biết chính xác.
+ * Có `suppressHydrationWarning` vì đồng hồ server và client gần như luôn lệch vài giây.
+ */
+declare function RelativeTime({ value, addSuffix, updateIntervalMs, titleFormat, fallback, className, ...props }: RelativeTimeProps): React.JSX.Element;
+
+export { RelativeTime, type RelativeTimeProps };

package/dist/components/composite/relative-time.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { format as formatDate, formatDistanceToNowStrict, isValid } from "date-fns";
+import { vi } from "date-fns/locale";
+import { useEffect, useState } from "react";
+function toDate(value) {
+  return value instanceof Date ? value : new Date(value);
+}
+function RelativeTime({
+  value,
+  addSuffix = true,
+  updateIntervalMs = 6e4,
+  titleFormat = "HH:mm 'ng\xE0y' dd/MM/yyyy",
+  fallback = "\u2014",
+  className,
+  ...props
+}) {
+  const date = toDate(value);
+  const valid = isValid(date);
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    if (!valid || !updateIntervalMs) return;
+    const timer = setInterval(() => setTick((current) => current + 1), updateIntervalMs);
+    return () => clearInterval(timer);
+  }, [valid, updateIntervalMs]);
+  if (!valid) {
+    return /* @__PURE__ */ jsx("span", { className, children: fallback });
+  }
+  return /* @__PURE__ */ jsx(
+    "time",
+    {
+      dateTime: date.toISOString(),
+      title: formatDate(date, titleFormat, { locale: vi }),
+      suppressHydrationWarning: true,
+      className,
+      ...props,
+      children: formatDistanceToNowStrict(date, { addSuffix, locale: vi })
+    }
+  );
+}
+export {
+  RelativeTime
+};
+//# sourceMappingURL=relative-time.js.map

package/dist/components/composite/relative-time.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/composite/relative-time.tsx"],"sourcesContent":["\"use client\";\n\nimport { format as formatDate, formatDistanceToNowStrict, isValid } from \"date-fns\";\nimport { vi } from \"date-fns/locale\";\nimport { type ComponentProps, useEffect, useState } from \"react\";\n\nexport interface RelativeTimeProps extends Omit<ComponentProps<\"time\">, \"dateTime\" | \"children\"> {\n  /** Thời điểm cần hiển thị: Date, ISO string hoặc epoch ms */\n  value: Date | string | number;\n  /** Thêm hậu tố \"trước\"/\"nữa\" (mặc định true) */\n  addSuffix?: boolean;\n  /** Chu kỳ tự cập nhật (ms). 0 = không tự cập nhật. Mặc định 60_000. */\n  updateIntervalMs?: number;\n  /** Định dạng của tooltip `title` (mặc định \"HH:mm 'ngày' dd/MM/yyyy\") */\n  titleFormat?: string;\n  /** Nội dung thay thế khi `value` không hợp lệ */\n  fallback?: string;\n}\n\nfunction toDate(value: Date | string | number): Date {\n  return value instanceof Date ? value : new Date(value);\n}\n\n/**\n * Thời gian tương đối kiểu \"3 phút trước\", tự cập nhật theo chu kỳ.\n *\n * Dùng `formatDistanceToNowStrict` (không phải bản thường): bản thường làm tròn kiểu \"khoảng 1\n * tháng\" cho mọi thứ từ 26 ngày đến 45 ngày — trong danh sách công việc thì \"26 ngày trước\" và\n * \"45 ngày trước\" là hai câu chuyện khác hẳn nhau.\n *\n * `title` luôn giữ mốc thời gian tuyệt đối để người dùng rà chuột là biết chính xác.\n * Có `suppressHydrationWarning` vì đồng hồ server và client gần như luôn lệch vài giây.\n */\nexport function RelativeTime({\n  value,\n  addSuffix = true,\n  updateIntervalMs = 60_000,\n  titleFormat = \"HH:mm 'ngày' dd/MM/yyyy\",\n  fallback = \"—\",\n  className,\n  ...props\n}: RelativeTimeProps) {\n  const date = toDate(value);\n  const valid = isValid(date);\n\n  const [, setTick] = useState(0);\n\n  useEffect(() => {\n    if (!valid || !updateIntervalMs) return;\n    const timer = setInterval(() => setTick((current) => current + 1), updateIntervalMs);\n    return () => clearInterval(timer);\n  }, [valid, updateIntervalMs]);\n\n  // Ngày hỏng (chuỗi rỗng, null từ API) → KHÔNG render <time>: thẻ này bắt buộc phải có\n  // `datetime` hợp lệ, đưa \"Invalid Date\" vào là tạo dữ liệu sai cho trình đọc màn hình và bộ máy tìm kiếm.\n  if (!valid) {\n    return <span className={className}>{fallback}</span>;\n  }\n\n  return (\n    <time\n      dateTime={date.toISOString()}\n      title={formatDate(date, titleFormat, { locale: vi })}\n      suppressHydrationWarning\n      className={className}\n      {...props}\n    >\n      {formatDistanceToNowStrict(date, { addSuffix, locale: vi })}\n    </time>\n  );\n}\n"],"mappings":";AAwDW;AAtDX,SAAS,UAAU,YAAY,2BAA2B,eAAe;AACzE,SAAS,UAAU;AACnB,SAA8B,WAAW,gBAAgB;AAezD,SAAS,OAAO,OAAqC;AACnD,SAAO,iBAAiB,OAAO,QAAQ,IAAI,KAAK,KAAK;AACvD;AAYO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA,YAAY;AAAA,EACZ,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,WAAW;AAAA,EACX;AAAA,EACA,GAAG;AACL,GAAsB;AACpB,QAAM,OAAO,OAAO,KAAK;AACzB,QAAM,QAAQ,QAAQ,IAAI;AAE1B,QAAM,CAAC,EAAE,OAAO,IAAI,SAAS,CAAC;AAE9B,YAAU,MAAM;AACd,QAAI,CAAC,SAAS,CAAC,iBAAkB;AACjC,UAAM,QAAQ,YAAY,MAAM,QAAQ,CAAC,YAAY,UAAU,CAAC,GAAG,gBAAgB;AACnF,WAAO,MAAM,cAAc,KAAK;AAAA,EAClC,GAAG,CAAC,OAAO,gBAAgB,CAAC;AAI5B,MAAI,CAAC,OAAO;AACV,WAAO,oBAAC,UAAK,WAAuB,oBAAS;AAAA,EAC/C;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,UAAU,KAAK,YAAY;AAAA,MAC3B,OAAO,WAAW,MAAM,aAAa,EAAE,QAAQ,GAAG,CAAC;AAAA,MACnD,0BAAwB;AAAA,MACxB;AAAA,MACC,GAAG;AAAA,MAEH,oCAA0B,MAAM,EAAE,WAAW,QAAQ,GAAG,CAAC;AAAA;AAAA,EAC5D;AAEJ;","names":[]}

package/dist/components/composite/search-filter-bar.d.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { Ref, ComponentPropsWithoutRef, ReactNode } from 'react';
+
+interface SearchFilterBarProps {
+    /** Giá trị ô tìm kiếm (controlled) */
+    searchValue: string;
+    onSearchChange: (value: string) => void;
+    searchPlaceholder?: string;
+    /** Trễ trước khi gọi `onSearchChange` (ms). 0 = gọi ngay. Gõ tìm gọi API thì đặt 250–350. */
+    debounceMs?: number;
+    searchInputRef?: Ref<HTMLInputElement>;
+    /** Props đặt thẳng lên ô nhập (id, name, aria-label, enterKeyHint…) */
+    searchInputProps?: ComponentPropsWithoutRef<"input">;
+    /** Slot bộ lọc cạnh ô tìm (Select, Combobox, DatePicker…) */
+    children?: ReactNode;
+    /** Slot hành động bên phải (nút Tạo mới, menu cột…) */
+    actions?: ReactNode;
+    /** Số bộ lọc đang bật — hiện huy hiệu và mở dòng đếm kết quả */
+    activeFilterCount?: number;
+    onClearFilters?: () => void;
+    /** Số bản ghi sau lọc */
+    resultCount?: number;
+    /** Tổng số bản ghi khi chưa lọc */
+    total?: number;
+    unitLabel?: string;
+    className?: string;
+}
+/**
+ * Thanh tìm kiếm + lọc chuẩn cho trang danh sách.
+ *
+ * Ô tìm giữ giá trị cục bộ và chỉ đẩy lên sau `debounceMs` — nếu bind thẳng vào state của trang,
+ * mỗi phím gõ là một lần render cả bảng (và thường là một request).
+ *
+ * Dòng đếm kết quả có `min-h-7` cố định để việc bật/tắt lọc không làm bảng nhảy lên xuống.
+ */
+declare function SearchFilterBar({ searchValue, onSearchChange, searchPlaceholder, debounceMs, searchInputRef, searchInputProps, children, actions, activeFilterCount, onClearFilters, resultCount, total, unitLabel, className }: SearchFilterBarProps): React.JSX.Element;
+
+export { SearchFilterBar, type SearchFilterBarProps };

package/dist/components/composite/search-filter-bar.js

@@ -0,0 +1,135 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Search, SlidersHorizontal, X } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { cn } from "../../lib/cn.js";
+import { Badge } from "../ui/badge.js";
+import { Button } from "../ui/button.js";
+import { Input } from "../ui/input.js";
+function SearchFilterBar({
+  searchValue,
+  onSearchChange,
+  searchPlaceholder = "T\xECm ki\u1EBFm\u2026",
+  debounceMs = 250,
+  searchInputRef,
+  searchInputProps,
+  children,
+  actions,
+  activeFilterCount = 0,
+  onClearFilters,
+  resultCount,
+  total,
+  unitLabel = "m\u1EE5c",
+  className
+}) {
+  const [localValue, setLocalValue] = useState(searchValue);
+  const lastEmittedRef = useRef(searchValue);
+  const timerRef = useRef(null);
+  const onSearchChangeRef = useRef(onSearchChange);
+  useEffect(() => {
+    onSearchChangeRef.current = onSearchChange;
+  });
+  useEffect(() => {
+    if (searchValue !== lastEmittedRef.current) {
+      lastEmittedRef.current = searchValue;
+      setLocalValue(searchValue);
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    }
+  }, [searchValue]);
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    []
+  );
+  const emit = (value) => {
+    setLocalValue(value);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    if (!debounceMs) {
+      lastEmittedRef.current = value;
+      onSearchChangeRef.current(value);
+      return;
+    }
+    timerRef.current = setTimeout(() => {
+      lastEmittedRef.current = value;
+      onSearchChangeRef.current(value);
+    }, debounceMs);
+  };
+  const clearSearch = () => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    setLocalValue("");
+    lastEmittedRef.current = "";
+    onSearchChangeRef.current("");
+  };
+  const hasFilters = activeFilterCount > 0;
+  const showCount = hasFilters || Boolean(localValue);
+  return /* @__PURE__ */ jsxs("div", { "data-slot": "search-filter-bar", className: cn("flex flex-col gap-2", className), children: [
+    /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [
+      /* @__PURE__ */ jsxs("div", { className: "relative min-w-[12rem] flex-1 sm:max-w-sm", children: [
+        /* @__PURE__ */ jsx(
+          Search,
+          {
+            "aria-hidden": "true",
+            className: "absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          Input,
+          {
+            ref: searchInputRef,
+            type: "search",
+            value: localValue,
+            placeholder: searchPlaceholder,
+            "aria-label": searchPlaceholder,
+            onChange: (event) => emit(event.target.value),
+            className: "pl-9 pr-8 [&::-webkit-search-cancel-button]:hidden",
+            ...searchInputProps
+          }
+        ),
+        localValue && /* @__PURE__ */ jsxs(
+          Button,
+          {
+            type: "button",
+            variant: "ghost",
+            size: "icon-sm",
+            onClick: clearSearch,
+            className: "absolute right-1 top-1/2 size-6 -translate-y-1/2",
+            children: [
+              /* @__PURE__ */ jsx(X, { "aria-hidden": "true", className: "size-3.5" }),
+              /* @__PURE__ */ jsx("span", { className: "sr-only", children: "X\xF3a t\u1EEB kh\xF3a" })
+            ]
+          }
+        )
+      ] }),
+      children,
+      hasFilters && /* @__PURE__ */ jsxs(Badge, { variant: "secondary", className: "gap-1", children: [
+        /* @__PURE__ */ jsx(SlidersHorizontal, { "aria-hidden": "true" }),
+        activeFilterCount,
+        " b\u1ED9 l\u1ECDc"
+      ] }),
+      actions && /* @__PURE__ */ jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })
+    ] }),
+    showCount && /* @__PURE__ */ jsxs("div", { role: "status", className: "flex min-h-7 items-center gap-2 text-sm text-muted-foreground", children: [
+      resultCount !== void 0 && /* @__PURE__ */ jsxs("span", { children: [
+        /* @__PURE__ */ jsx("strong", { className: "font-medium text-foreground tabular-nums", children: resultCount }),
+        total !== void 0 ? ` / ${total}` : "",
+        " ",
+        unitLabel
+      ] }),
+      hasFilters && onClearFilters && /* @__PURE__ */ jsxs(Button, { type: "button", variant: "ghost", size: "sm", onClick: onClearFilters, className: "h-7 gap-1.5 px-2", children: [
+        /* @__PURE__ */ jsx(X, { "aria-hidden": "true", className: "size-3.5" }),
+        "X\xF3a l\u1ECDc"
+      ] })
+    ] })
+  ] });
+}
+export {
+  SearchFilterBar
+};
+//# sourceMappingURL=search-filter-bar.js.map

package/dist/components/composite/search-filter-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/composite/search-filter-bar.tsx"],"sourcesContent":["\"use client\";\n\nimport { Search, SlidersHorizontal, X } from \"lucide-react\";\nimport { type ComponentPropsWithoutRef, type ReactNode, type Ref, useEffect, useRef, useState } from \"react\";\nimport { cn } from \"../../lib/cn.js\";\nimport { Badge } from \"../ui/badge.js\";\nimport { Button } from \"../ui/button.js\";\nimport { Input } from \"../ui/input.js\";\n\nexport interface SearchFilterBarProps {\n  /** Giá trị ô tìm kiếm (controlled) */\n  searchValue: string;\n  onSearchChange: (value: string) => void;\n  searchPlaceholder?: string;\n  /** Trễ trước khi gọi `onSearchChange` (ms). 0 = gọi ngay. Gõ tìm gọi API thì đặt 250–350. */\n  debounceMs?: number;\n  searchInputRef?: Ref<HTMLInputElement>;\n  /** Props đặt thẳng lên ô nhập (id, name, aria-label, enterKeyHint…) */\n  searchInputProps?: ComponentPropsWithoutRef<\"input\">;\n\n  /** Slot bộ lọc cạnh ô tìm (Select, Combobox, DatePicker…) */\n  children?: ReactNode;\n  /** Slot hành động bên phải (nút Tạo mới, menu cột…) */\n  actions?: ReactNode;\n\n  /** Số bộ lọc đang bật — hiện huy hiệu và mở dòng đếm kết quả */\n  activeFilterCount?: number;\n  onClearFilters?: () => void;\n  /** Số bản ghi sau lọc */\n  resultCount?: number;\n  /** Tổng số bản ghi khi chưa lọc */\n  total?: number;\n  unitLabel?: string;\n  className?: string;\n}\n\n/**\n * Thanh tìm kiếm + lọc chuẩn cho trang danh sách.\n *\n * Ô tìm giữ giá trị cục bộ và chỉ đẩy lên sau `debounceMs` — nếu bind thẳng vào state của trang,\n * mỗi phím gõ là một lần render cả bảng (và thường là một request).\n *\n * Dòng đếm kết quả có `min-h-7` cố định để việc bật/tắt lọc không làm bảng nhảy lên xuống.\n */\nexport function SearchFilterBar({\n  searchValue,\n  onSearchChange,\n  searchPlaceholder = \"Tìm kiếm…\",\n  debounceMs = 250,\n  searchInputRef,\n  searchInputProps,\n  children,\n  actions,\n  activeFilterCount = 0,\n  onClearFilters,\n  resultCount,\n  total,\n  unitLabel = \"mục\",\n  className\n}: SearchFilterBarProps) {\n  const [localValue, setLocalValue] = useState(searchValue);\n  const lastEmittedRef = useRef(searchValue);\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const onSearchChangeRef = useRef(onSearchChange);\n\n  useEffect(() => {\n    onSearchChangeRef.current = onSearchChange;\n  });\n\n  // Đồng bộ khi giá trị bị đổi từ bên ngoài (nút \"Xóa lọc\", điều hướng lại trang) — nhưng\n  // không đè lên những gì người dùng đang gõ dở.\n  useEffect(() => {\n    if (searchValue !== lastEmittedRef.current) {\n      lastEmittedRef.current = searchValue;\n      setLocalValue(searchValue);\n      if (timerRef.current) {\n        clearTimeout(timerRef.current);\n        timerRef.current = null;\n      }\n    }\n  }, [searchValue]);\n\n  useEffect(\n    () => () => {\n      if (timerRef.current) clearTimeout(timerRef.current);\n    },\n    []\n  );\n\n  const emit = (value: string) => {\n    setLocalValue(value);\n    if (timerRef.current) clearTimeout(timerRef.current);\n    if (!debounceMs) {\n      lastEmittedRef.current = value;\n      onSearchChangeRef.current(value);\n      return;\n    }\n    timerRef.current = setTimeout(() => {\n      lastEmittedRef.current = value;\n      onSearchChangeRef.current(value);\n    }, debounceMs);\n  };\n\n  const clearSearch = () => {\n    if (timerRef.current) {\n      clearTimeout(timerRef.current);\n      timerRef.current = null;\n    }\n    setLocalValue(\"\");\n    lastEmittedRef.current = \"\";\n    onSearchChangeRef.current(\"\");\n  };\n\n  const hasFilters = activeFilterCount > 0;\n  const showCount = hasFilters || Boolean(localValue);\n\n  return (\n    <div data-slot=\"search-filter-bar\" className={cn(\"flex flex-col gap-2\", className)}>\n      <div className=\"flex flex-wrap items-center gap-2\">\n        <div className=\"relative min-w-[12rem] flex-1 sm:max-w-sm\">\n          <Search\n            aria-hidden=\"true\"\n            className=\"absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground\"\n          />\n          <Input\n            ref={searchInputRef}\n            type=\"search\"\n            value={localValue}\n            placeholder={searchPlaceholder}\n            aria-label={searchPlaceholder}\n            onChange={(event) => emit(event.target.value)}\n            className=\"pl-9 pr-8 [&::-webkit-search-cancel-button]:hidden\"\n            {...searchInputProps}\n          />\n          {localValue && (\n            <Button\n              type=\"button\"\n              variant=\"ghost\"\n              size=\"icon-sm\"\n              onClick={clearSearch}\n              className=\"absolute right-1 top-1/2 size-6 -translate-y-1/2\"\n            >\n              <X aria-hidden=\"true\" className=\"size-3.5\" />\n              <span className=\"sr-only\">Xóa từ khóa</span>\n            </Button>\n          )}\n        </div>\n\n        {children}\n\n        {hasFilters && (\n          <Badge variant=\"secondary\" className=\"gap-1\">\n            <SlidersHorizontal aria-hidden=\"true\" />\n            {activeFilterCount} bộ lọc\n          </Badge>\n        )}\n\n        {actions && <div className=\"ml-auto flex items-center gap-2\">{actions}</div>}\n      </div>\n\n      {showCount && (\n        <div role=\"status\" className=\"flex min-h-7 items-center gap-2 text-sm text-muted-foreground\">\n          {resultCount !== undefined && (\n            <span>\n              <strong className=\"font-medium text-foreground tabular-nums\">{resultCount}</strong>\n              {total !== undefined ? ` / ${total}` : \"\"} {unitLabel}\n            </span>\n          )}\n          {hasFilters && onClearFilters && (\n            <Button type=\"button\" variant=\"ghost\" size=\"sm\" onClick={onClearFilters} className=\"h-7 gap-1.5 px-2\">\n              <X aria-hidden=\"true\" className=\"size-3.5\" />\n              Xóa lọc\n            </Button>\n          )}\n        </div>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/composite/stat-card.d.ts

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { ComponentProps, ReactNode } from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import { IconComponent } from './empty-state.js';
+
+/** Ô icon của StatCard, tô theo tone token (không hex). */
+declare const statCardIconVariants: (props?: ({
+    tone?: "default" | "primary" | "success" | "warning" | "destructive" | "info" | "app" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type StatCardTone = NonNullable<VariantProps<typeof statCardIconVariants>["tone"]>;
+type StatCardDeltaDirection = "up" | "down" | "flat";
+interface StatCardDelta {
+    /** Nội dung hiển thị, vd "+12,5%" hoặc "3 việc" */
+    value: ReactNode;
+    direction: StatCardDeltaDirection;
+    /**
+     * Tăng là TỐT hay XẤU — mặc định "positive-up" (tăng = tốt).
+     *
+     * Cần thiết vì có chỉ số ngược chiều: số ticket quá hạn tăng là xấu, tỷ lệ rời bỏ giảm là tốt.
+     * Tô màu theo hướng mũi tên một cách máy móc sẽ nói dối người đọc.
+     */
+    polarity?: "positive-up" | "positive-down" | "neutral";
+    /** Chú thích sau con số, vd "so với tuần trước" */
+    label?: ReactNode;
+}
+interface StatCardProps extends Omit<ComponentProps<"div">, "title"> {
+    /** Nhãn chỉ số, vd "Việc đang mở" */
+    label: ReactNode;
+    value: ReactNode;
+    icon?: IconComponent;
+    tone?: StatCardTone;
+    delta?: StatCardDelta;
+    /** Slot biểu đồ mini (sparkline) — package không ép thư viện biểu đồ nào */
+    sparkline?: ReactNode;
+    /** Dòng chú thích dưới cùng */
+    footer?: ReactNode;
+    /** Đang tải → khung xương thay cho số liệu */
+    loading?: boolean;
+}
+/**
+ * Thẻ KPI: nhãn + số liệu lớn + biến động + sparkline tuỳ chọn.
+ *
+ * Số liệu dùng `tabular-nums` để cột số không nhảy khi cập nhật realtime. Tĩnh → RSC-safe.
+ */
+declare function StatCard({ label, value, icon: Icon, tone, delta, sparkline, footer, loading, className, ...props }: StatCardProps): React.JSX.Element;
+
+export { StatCard, type StatCardDelta, type StatCardDeltaDirection, type StatCardProps, type StatCardTone, statCardIconVariants };