create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/app/ui-kit/src/ui/date-picker/index.tsx

@@ -0,0 +1,287 @@
+// DatePicker — Calendar + trigger input (popup panel). Motion: fade+zoom khi mở.
+// Batch ⑧ worker C: + range mode (2 input from/to, click start → end, hover
+// preview highlight khoảng như antd RangePicker) + showTime (cột TimeSpinner
+// bên phải panel, xác nhận bằng OK — antd style) + locale (vi/en) + now inject.
+// Single mode GIỮ NGUYÊN behavior cũ: click ngày → onChange + đóng panel.
+import { useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { Calendar } from '../calendar/index.js';
+import { TimeSpinner, type TimeParts } from '../time-picker/index.js';
+import { useDateLocale, type DateLocaleInput } from './locale.js';
+import { Icon } from '../icons/index.js';
+
+export interface DatePickerBaseProps {
+  placeholder?: string;
+  disabled?: boolean;
+  /** Node hiển thị trước input (icon). */
+  prefix?: ReactNode;
+  /** Chọn giờ phụ bên phải panel — panel mở đến khi nhấn OK. */
+  showTime?: boolean;
+  /** 'vi' | 'en' | DateLocale — thắng DateLocaleProvider context; default vi. */
+  locale?: DateLocaleInput;
+  /** Mốc "hôm nay" — inject được để test deterministic. */
+  now?: Date;
+  className?: string;
+}
+
+export interface DatePickerSingleProps extends DatePickerBaseProps {
+  range?: false;
+  value?: Date;
+  onChange?: (date: Date) => void;
+}
+
+export interface DatePickerRangeProps extends DatePickerBaseProps {
+  /** Range mode — 2 input from/to + panel chọn khoảng. */
+  range: true;
+  value?: [Date, Date];
+  onChange?: (range: [Date, Date]) => void;
+}
+
+export type DatePickerProps = DatePickerSingleProps | DatePickerRangeProps;
+
+const pad = (n: number) => n.toString().padStart(2, '0');
+const fmt = (d: Date) => `${pad(d.getDate())}/${pad(d.getMonth() + 1)}/${d.getFullYear()}`;
+
+function parseTime(value: Date | [Date, Date] | undefined): TimeParts {
+  const first = Array.isArray(value) ? value[0] : value;
+  return first ? { h: first.getHours(), m: first.getMinutes() } : { h: 0, m: 0 };
+}
+
+export function DatePicker(props: DatePickerProps) {
+  const {
+    range = false,
+    showTime = false,
+    placeholder,
+    disabled = false,
+    prefix,
+    className,
+    locale,
+    now = new Date(),
+  } = props;
+  const value = props.value;
+  const onChange = props.onChange as ((v: Date | [Date, Date]) => void) | undefined;
+  const loc = useDateLocale(locale);
+
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLSpanElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  // Responsive 375 (bugfix PO): đo panel sau layout → clamp cạnh phải + flip đáy
+  // theo size THẬT (fallback = min-w 300 / ~360 chiều cao calendar+footer khi chưa đo).
+  const [panelW, setPanelW] = useState(0);
+  const [panelH, setPanelH] = useState(0);
+  useLayoutEffect(() => {
+    if (!open) return;
+    const el = panelRef.current;
+    if (!el) return;
+    // ResizeObserver: panel đổi size SAU khi mở (font load, wrap lại theo viewport,
+    // scrollbar canvas) → clamp/flip phải theo size MỚI, không đo 1 lần bị stale.
+    const measure = () => { setPanelW(el.offsetWidth); setPanelH(el.offsetHeight); };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return; // jsdom — fallback min-w còn đúng
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [open]);
+
+  // Range draft — sync từ value mỗi lần mở panel (antd: mở lại = chọn lại)
+  const [draft, setDraft] = useState<{ start: Date | null; end: Date | null }>({ start: null, end: null });
+  const [phase, setPhase] = useState<'from' | 'to'>('from');
+  const [hover, setHover] = useState<Date | null>(null);
+  // Single + showTime: ngày đang pick (date-part) để compose với time spinner
+  const [picked, setPicked] = useState<Date | null>(null);
+  const [time, setTime] = useState<TimeParts>({ h: 0, m: 0 });
+
+  const openPanel = () => {
+    if (disabled) return;
+    if (range) {
+      const [s, e] = Array.isArray(value) ? value : [undefined, undefined];
+      setDraft({ start: s ?? null, end: e ?? null });
+      setPhase('from');
+    } else {
+      setPicked(!Array.isArray(value) && value ? value : null);
+    }
+    setTime(parseTime(value));
+    setHover(null);
+    setOpen(true);
+  };
+
+  /** Gộp date-part với time draft khi showTime. */
+  const compose = (d: Date, t: TimeParts = time): Date =>
+    showTime ? new Date(d.getFullYear(), d.getMonth(), d.getDate(), t.h, t.m) : d;
+
+  const handleDay = (d: Date) => {
+    if (range) {
+      if (phase === 'from' || (draft.start && draft.end)) {
+        setDraft({ start: d, end: null });
+        setPhase('to');
+        return;
+      }
+      const start = draft.start as Date;
+      const [s, e] = d >= start ? [start, d] : [d, start];
+      setDraft({ start: s, end: e });
+      setPhase('from');
+      onChange?.([compose(s), compose(e)] as [Date, Date]);
+      if (!showTime) setOpen(false);
+    } else {
+      setPicked(d);
+      onChange?.(compose(d));
+      if (!showTime) setOpen(false); // behavior cũ: single không showTime → click là đóng
+    }
+  };
+
+  const handleTime = (t: TimeParts) => {
+    setTime(t);
+    if (range) {
+      if (draft.start && draft.end) onChange?.([compose(draft.start, t), compose(draft.end, t)] as [Date, Date]);
+    } else if (picked) {
+      onChange?.(compose(picked, t));
+    }
+  };
+
+  const handleToday = () => {
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    if (range) onChange?.([compose(today), compose(today)] as [Date, Date]);
+    else onChange?.(compose(today));
+    setOpen(false);
+  };
+
+  const handleOk = () => {
+    if (range && draft.start && draft.end) {
+      onChange?.([compose(draft.start), compose(draft.end)] as [Date, Date]);
+    }
+    setOpen(false);
+  };
+
+  const displayTime = () => (showTime ? ` ${pad(time.h)}:${pad(time.m)}` : '');
+
+  // ── Trigger ──────────────────────────────────────────────────────────────
+  // Single: 1 field button (behavior cũ). Range: wrapper viền + 2 nửa from/to.
+  const triggerCls = `inline-flex h-8 w-full cursor-pointer items-center gap-2 rounded-lg border bg-s3 px-3 text-body shadow-[var(--ele-1)] transition-[background-color,border-color,box-shadow] duration-200 ease-[var(--ease-smooth)] hover:shadow-[var(--ele-2)] focus-visible:ring-[3px] focus-visible:ring-accent/40 focus-visible:outline-none ${
+    open ? 'border-accent-hi' : 'border-line hover:border-ink/20'
+  } ${disabled ? 'cursor-not-allowed bg-s3 text-ink4 shadow-none' : 'text-ink'}`;
+
+  let trigger: ReactNode;
+  if (range) {
+    const [from, to] = Array.isArray(value) ? value : [undefined, undefined];
+    trigger = (
+      <span className={triggerCls}>
+        {prefix}
+        <button
+          type="button"
+          aria-label={loc.rangeFrom}
+          disabled={disabled}
+          onClick={openPanel}
+          className="min-w-0 flex-1 cursor-pointer border-none bg-transparent p-0 text-left text-inherit"
+        >
+          <span className={from ? '' : 'text-ink'}>{from ? `${fmt(from)}${displayTime()}` : placeholder ?? loc.rangeFrom}</span>
+        </button>
+        <span aria-hidden="true" className="text-ink3"><Icon name="arrow-right" size={12} /></span>
+        <button
+          type="button"
+          aria-label={loc.rangeTo}
+          disabled={disabled}
+          onClick={openPanel}
+          className="min-w-0 flex-1 cursor-pointer border-none bg-transparent p-0 text-left text-inherit"
+        >
+          <span className={to ? '' : 'text-ink'}>{to ? `${fmt(to)}${displayTime()}` : placeholder ?? loc.rangeTo}</span>
+        </button>
+        <span aria-hidden="true" className="ml-auto shrink-0 text-ink3"><Icon name="calendar" size={14} /></span>
+      </span>
+    );
+  } else {
+    const single = !Array.isArray(value) ? value : undefined;
+    trigger = (
+      <span className={triggerCls}>
+        {prefix}
+        <button
+          type="button"
+          aria-label={single ? `${loc.dateValuePrefix} ${fmt(single)}` : loc.triggerLabel}
+          disabled={disabled}
+          onClick={openPanel}
+          className="min-w-0 flex-1 cursor-pointer border-none bg-transparent p-0 text-left text-inherit"
+        >
+          <span className={single ? 'tabular-nums' : 'text-ink'}>
+            {single ? `${fmt(single)}${displayTime()}` : placeholder ?? loc.placeholder}
+          </span>
+        </button>
+        <span aria-hidden="true" className="ml-auto shrink-0 text-ink3"><Icon name="calendar" size={14} /></span>
+      </span>
+    );
+  }
+
+  // Vị trí panel: bottom-start mặc định; clamp lề phải (margin 8) khi trigger sát
+  // phải; flip lên trên khi không đủ chỗ phía dưới (không che trigger).
+  const rect = ref.current?.getBoundingClientRect();
+  const vw = typeof window === 'undefined' ? 1280 : window.innerWidth;
+  const vh = typeof window === 'undefined' ? 800 : window.innerHeight;
+  const PANEL_W_FALLBACK = 300; // = min-w panel
+  const PANEL_H_FALLBACK = 360; // ≈ calendar 6 hàng + footer
+  const panelWidth = panelW || PANEL_W_FALLBACK;
+  const panelHeight = panelH || PANEL_H_FALLBACK;
+  const flipUp = rect != null && rect.bottom + 8 + panelHeight > vh;
+  const posStyle: CSSProperties = {
+    left: Math.max(8, Math.min(rect?.left ?? 0, vw - 8 - panelWidth)),
+    ...(flipUp ? { bottom: vh - (rect?.top ?? 0) + 4 } : { top: (rect?.bottom ?? 0) + 4 }),
+  };
+
+  return (
+    <span ref={ref} className={`relative inline-flex${className ? ` ${className}` : ''}`}>
+      {trigger}
+      {open && createPortal(
+        <div className="fixed inset-0 z-[var(--z-popover)]" onClick={() => setOpen(false)}>
+          <div
+            className="absolute animate-[bp-zoom-in_var(--motion-base)_var(--ease-enter)]"
+            style={posStyle}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <div
+              ref={panelRef}
+              className="min-w-[300px] max-w-[calc(100vw-16px)] rounded-xl border border-line bg-s2 bg-[image:var(--wash)] shadow-[var(--shadow-pop),var(--ele-3)]"
+            >
+              <div className={showTime ? 'flex flex-wrap items-start gap-3' : ''}>
+                <Calendar
+                  now={now}
+                  locale={locale}
+                  bare
+                  value={range ? (draft.start ?? undefined) : picked ?? undefined}
+                  onChange={handleDay}
+                  onDayHover={range && phase === 'to' ? (d) => setHover(d) : undefined}
+                  range={
+                    range
+                      ? { start: draft.start, end: draft.end, hover: phase === 'to' ? hover : null }
+                      : undefined
+                  }
+                />
+                {showTime && (
+                  <div className="min-w-0 w-[150px] border-l border-line2 pl-3 pt-9">
+                    <TimeSpinner value={time} onChange={handleTime} locale={locale} />
+                  </div>
+                )}
+              </div>
+              {/* Footer — Hôm nay luôn có; OK chỉ khi showTime (antd: confirm đóng panel) */}
+              <div className="flex items-center justify-end gap-2 border-t border-line2 px-4 py-2">
+                <button
+                  type="button"
+                  onClick={handleToday}
+                  className="cursor-pointer rounded-lg border-none bg-transparent px-3 py-1.5 text-label text-accent transition-colors duration-200 ease-[var(--ease-smooth)] hover:bg-accent/10"
+                >
+                  {loc.today}
+                </button>
+                {showTime && (
+                  <button
+                    type="button"
+                    onClick={handleOk}
+                    className="cursor-pointer rounded-lg bg-accent px-3 py-1.5 text-label font-medium text-white transition-[opacity,transform] duration-200 ease-[var(--ease-smooth)] hover:opacity-90 active:translate-y-px"
+                  >
+                    {loc.ok}
+                  </button>
+                )}
+              </div>
+            </div>
+          </div>
+        </div>,
+        document.body,
+      )}
+    </span>
+  );
+}

package/stack-template/app/ui-kit/src/ui/date-picker/locale-constants.ts

@@ -0,0 +1,90 @@
+// Locale constants + hook cho date-picker/calendar/time-picker (tách khỏi locale.tsx
+// để react-refresh/only-export-components sạch — file này không export component nào).
+// Chia sẻ qua DateLocaleProvider (context, xem locale.tsx) HOẶC prop `locale` từng component
+// (prop thắng context, default 'vi').
+import { createContext, useContext } from 'react';
+
+export interface DateLocale {
+  months: string[]; // 12 tên tháng (vd 'Tháng 1' / 'January')
+  /** 7 label ngày trong tuần — xếp theo thứ tự BẮT ĐẦU từ firstDayOfWeek. */
+  weekdays: string[];
+  /** 0 = Chủ nhật đầu tuần (en), 1 = Thứ hai đầu tuần (vi). */
+  firstDayOfWeek: 0 | 1;
+  prevMonth: string; // aria nút tháng trước
+  nextMonth: string; // aria nút tháng sau
+  today: string; // nút chân panel
+  now: string; // nút nhanh TimePicker
+  ok: string; // nút xác nhận (showTime)
+  placeholder: string;
+  triggerLabel: string; // aria trigger single
+  rangeFrom: string; // aria/label input from
+  rangeTo: string; // aria/label input to
+  hour: string;
+  minute: string;
+  increase: string; // aria btn tăng (vd 'Tăng')
+  decrease: string; // aria btn giảm
+  timeTriggerLabel: string; // aria trigger TimePicker khi trống
+  timeValuePrefix: string; // aria trigger khi có value (vd 'Giờ:')
+  dateValuePrefix: string; // aria trigger DatePicker khi có value (vd 'Ngày:')
+}
+
+export const VI_LOCALE: DateLocale = {
+  months: ['Tháng 1','Tháng 2','Tháng 3','Tháng 4','Tháng 5','Tháng 6','Tháng 7','Tháng 8','Tháng 9','Tháng 10','Tháng 11','Tháng 12'],
+  weekdays: ['T2', 'T3', 'T4', 'T5', 'T6', 'T7', 'CN'],
+  firstDayOfWeek: 1,
+  prevMonth: 'Tháng trước',
+  nextMonth: 'Tháng sau',
+  today: 'Hôm nay',
+  now: 'Bây giờ',
+  ok: 'OK',
+  placeholder: 'Chọn ngày…',
+  triggerLabel: 'Chọn ngày',
+  rangeFrom: 'Từ ngày',
+  rangeTo: 'Đến ngày',
+  hour: 'Giờ',
+  minute: 'Phút',
+  increase: 'Tăng',
+  decrease: 'Giảm',
+  timeTriggerLabel: 'Chọn giờ',
+  timeValuePrefix: 'Giờ:',
+  dateValuePrefix: 'Ngày:',
+};
+
+export const EN_LOCALE: DateLocale = {
+  months: ['January','February','March','April','May','June','July','August','September','October','November','December'],
+  weekdays: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
+  firstDayOfWeek: 0,
+  prevMonth: 'Previous month',
+  nextMonth: 'Next month',
+  today: 'Today',
+  now: 'Now',
+  ok: 'OK',
+  placeholder: 'Pick a date…',
+  triggerLabel: 'Pick date',
+  rangeFrom: 'From date',
+  rangeTo: 'To date',
+  hour: 'Hour',
+  minute: 'Minute',
+  increase: 'Increase',
+  decrease: 'Decrease',
+  timeTriggerLabel: 'Pick time',
+  timeValuePrefix: 'Time:',
+  dateValuePrefix: 'Date:',
+};
+
+export type DateLocaleInput = 'vi' | 'en' | DateLocale;
+
+export function resolveDateLocale(locale?: DateLocaleInput): DateLocale {
+  if (!locale || locale === 'vi') return VI_LOCALE;
+  if (locale === 'en') return EN_LOCALE;
+  return locale;
+}
+
+export const LocaleContext = createContext<DateLocale>(VI_LOCALE);
+
+/** Prop `locale` thắng context; không có cả hai → vi. */
+export function useDateLocale(locale?: DateLocaleInput): DateLocale {
+  const ctx = useContext(LocaleContext);
+  return locale ? resolveDateLocale(locale) : ctx;
+}
+

package/stack-template/app/ui-kit/src/ui/date-picker/locale.tsx

@@ -0,0 +1,15 @@
+// Locale cho date-picker/calendar/time-picker (batch ⑧ worker C) — nhẹ, không i18n lib.
+// File này chỉ export COMPONENT (DateLocaleProvider); constants + hook nằm ở locale-constants.ts
+// (react-refresh/only-export-components). Re-export value ở dưới để GIỮ NGUYÊN import path cũ
+// (calendar/time-picker/timesheet/src-index đang import từ module này).
+export type { DateLocale, DateLocaleInput } from './locale-constants.js';
+// eslint-disable-next-line react-refresh/only-export-components -- giữ ổn định import path cho consumer cũ; đáng lẽ trỏ thẳng locale-constants (timesheet đang giữ file — không chỉnh được)
+export { VI_LOCALE, EN_LOCALE, resolveDateLocale, LocaleContext, useDateLocale } from './locale-constants.js';
+import { LocaleContext, resolveDateLocale, type DateLocaleInput } from './locale-constants.js';
+import type { ReactNode } from 'react';
+
+/** Provider chia sẻ locale cho DatePicker/Calendar/TimePicker bên dưới (không bắt buộc — prop ưu tiên hơn). */
+export function DateLocaleProvider({ locale = 'vi', children }: { locale?: DateLocaleInput; children: ReactNode }) {
+  const resolved = resolveDateLocale(locale);
+  return <LocaleContext.Provider value={resolved}>{children}</LocaleContext.Provider>;
+}

package/stack-template/app/ui-kit/src/ui/deferred-content/deferred-content.stories.tsx

@@ -0,0 +1,62 @@
+// DeferredContent stories — skeleton placeholder, swap on scroll into view.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DeferredContent } from './index';
+
+/** Lazy content swap — IntersectionObserver fires once on scroll into view. */
+const meta = { title: 'Primitives/DeferredContent', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Basic — scroll this block into view: skeleton swaps to the loaded card once. */
+export const Basic: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="h-40 rounded-xl border border-line bg-s2 p-4 text-body text-ink3">
+        Scroll down ↓ — the deferred block loads when it enters the viewport.
+      </div>
+      <DeferredContent onVisible={() => console.log('[DeferredContent] visible')}>
+        <div className="rounded-xl border border-line bg-s1 p-4">
+          <p className="m-0 text-body text-ink">Loaded — chart, map or editor mounts only now.</p>
+        </div>
+      </DeferredContent>
+      <div className="h-40" />
+    </div>
+  ),
+};
+
+/** CustomPlaceholder — own loading node instead of the default skeleton card. */
+export const CustomPlaceholder: Story = {
+  name: 'Custom placeholder',
+  render: () => (
+    <DeferredContent placeholder={<div className="rounded-xl border border-dashed border-line p-4 text-label text-ink3">Queueing task…</div>}>
+      <div className="rounded-xl border border-line bg-s1 p-4">
+        <p className="m-0 text-body text-ink">Custom content in place.</p>
+      </div>
+    </DeferredContent>
+  ),
+};
+
+/** LoadOnInit — skips the observer; children mount immediately. */
+export const LoadOnInit: Story = {
+  name: 'LoadOnInit — no waiting',
+  render: () => (
+    <DeferredContent loadOnInit>
+      <div className="rounded-xl border border-line bg-s1 p-4">
+        <p className="m-0 text-body text-ink">Rendered right away — useful above the fold.</p>
+      </div>
+    </DeferredContent>
+  ),
+};
+
+/** DarkTheme — placeholder bones follow tokens. */
+export const DarkTheme: Story = {
+  render: () => (
+    <div data-bp-theme="dark" className="p-2">
+      <DeferredContent>
+        <div className="rounded-xl border border-line bg-s1 p-4">
+          <p className="m-0 text-body text-ink">Dark content.</p>
+        </div>
+      </DeferredContent>
+    </div>
+  ),
+};

package/stack-template/app/ui-kit/src/ui/deferred-content/deferred-content.test.tsx

@@ -0,0 +1,94 @@
+// DeferredContent tests — placeholder trước, IO trigger 1 lần, loadOnInit,
+// custom placeholder, fallback khi không có IntersectionObserver.
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { DeferredContent } from './index.js';
+
+class MockIO {
+  static instances: MockIO[] = [];
+  disconnected = false;
+  constructor(
+    public cb: IntersectionObserverCallback,
+    public options?: IntersectionObserverInit,
+  ) {
+    MockIO.instances.push(this);
+  }
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn(() => {
+    this.disconnected = true;
+  });
+  trigger(isIntersecting: boolean) {
+    act(() => {
+      this.cb([{ isIntersecting, target: {} } as IntersectionObserverEntry], this as unknown as IntersectionObserver);
+    });
+  }
+}
+
+beforeEach(() => {
+  MockIO.instances = [];
+  vi.stubGlobal('IntersectionObserver', MockIO);
+});
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+const last = () => MockIO.instances[MockIO.instances.length - 1]!;
+
+describe('DeferredContent', () => {
+  it('chưa thấy → placeholder skeleton (role=status), children ẩn', () => {
+    render(
+      <DeferredContent>
+        <p>Nội dung nặng</p>
+      </DeferredContent>,
+    );
+    // Skeleton wrapper mỗi bone đều role=status → dùng getAllByRole
+    expect(screen.getAllByRole('status').length).toBeGreaterThan(0);
+    expect(screen.queryByText('Nội dung nặng')).toBeNull();
+  });
+
+  it('IO intersect → children hiện + onVisible gọi đúng 1 lần + observer disconnect', () => {
+    const onVisible = vi.fn();
+    render(
+      <DeferredContent onVisible={onVisible}>
+        <p>Nội dung nặng</p>
+      </DeferredContent>,
+    );
+    last().trigger(true);
+    expect(screen.getByText('Nội dung nặng')).toBeInTheDocument();
+    expect(onVisible).toHaveBeenCalledTimes(1);
+    expect(last().disconnected).toBe(true);
+    // trigger nữa không gọi lại (fired guard)
+    last().trigger(true);
+    expect(onVisible).toHaveBeenCalledTimes(1);
+  });
+
+  it('loadOnInit → children hiện ngay, không tạo observer', () => {
+    render(
+      <DeferredContent loadOnInit onVisible={() => {}}>
+        <p>Nạp ngay</p>
+      </DeferredContent>,
+    );
+    expect(screen.getByText('Nạp ngay')).toBeInTheDocument();
+    expect(MockIO.instances).toHaveLength(0);
+  });
+
+  it('custom placeholder render thay skeleton mặc định', () => {
+    render(
+      <DeferredContent placeholder={<div role="status">Đang xếp hàng…</div>}>
+        <p>x</p>
+      </DeferredContent>,
+    );
+    expect(screen.getByText('Đang xếp hàng…')).toBeInTheDocument();
+  });
+
+  it('không có IntersectionObserver trong môi trường → fallback load luôn', () => {
+    vi.unstubAllGlobals();
+    render(
+      <DeferredContent>
+        <p>Fallback</p>
+      </DeferredContent>,
+    );
+    expect(screen.getByText('Fallback')).toBeInTheDocument();
+  });
+});

package/stack-template/app/ui-kit/src/ui/deferred-content/index.tsx

@@ -0,0 +1,61 @@
+// DeferredContent — trì hoãn render nội dung nặng đến khi cuộn tới nhìn thấy
+// (PrimeReact lite): IntersectionObserver 1 lần, fallback loadOnInit.
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { Skeleton } from '../skeleton/index.js';
+
+export interface DeferredContentProps {
+  /** Gọi MỘT LẦN khi nội dung vào viewport. */
+  onVisible?: () => void;
+  /** Bỏ qua observer — load ngay khi mount. */
+  loadOnInit?: boolean;
+  /** Placeholder trước khi load (mặc định: skeleton card). */
+  placeholder?: ReactNode;
+  /** Ngưỡng hiện của target (0–1), mặc định 0.2. */
+  threshold?: number;
+  children: ReactNode;
+  className?: string;
+}
+
+export function DeferredContent({ onVisible, loadOnInit = false, placeholder, threshold = 0.2, children, className }: DeferredContentProps) {
+  const [visible, setVisible] = useState(loadOnInit);
+  const ref = useRef<HTMLDivElement>(null);
+  const fired = useRef(false);
+
+  useEffect(() => {
+    if (loadOnInit || visible) return;
+    const el = ref.current;
+    if (!el) return;
+    if (typeof IntersectionObserver === 'undefined') {
+      // Fallback môi trường không có IO: load luôn (không treo placeholder vĩnh viễn).
+      setVisible(true);
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting) || fired.current) return;
+        fired.current = true;
+        setVisible(true);
+        onVisible?.();
+        io.disconnect();
+      },
+      { threshold },
+    );
+    io.observe(el);
+    return () => io.disconnect();
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- onVisible/consumer callback: chỉ chạy 1 lần khi mount
+  }, [loadOnInit, threshold]);
+
+  return (
+    <div ref={ref} className={className}>
+      {visible ? children : (placeholder ?? (
+        <div className="flex gap-3 rounded-xl border border-line bg-s2 p-4" aria-busy="true" aria-label="Đang tải">
+          <Skeleton variant="circle" />
+          <div className="flex flex-1 flex-col gap-2">
+            <Skeleton variant="text" />
+            <Skeleton variant="row" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}