sh-ui-cli 0.43.0 → 0.44.0

package/data/registry/react/components/dialog/index.tailwind.tsx

@@ -0,0 +1,96 @@
+import * as React from "react";
+import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+
+type WithStringClassName<T> = Omit<T, "className"> & { className?: string };
+
+function cx(...args: (string | undefined | false)[]) {
+  return args.filter(Boolean).join(" ");
+}
+
+export const Dialog = BaseDialog.Root;
+export const DialogTrigger = BaseDialog.Trigger;
+export const DialogClose = BaseDialog.Close;
+
+export function DialogCloseX({ className, children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  return (
+    <BaseDialog.Close
+      className={cx(
+        "absolute top-[var(--space-3)] right-[var(--space-3)] inline-flex items-center justify-center w-8 h-8 border-0 rounded-[calc(var(--radius)-2px)] bg-transparent text-foreground-muted text-[length:var(--text-lg)] leading-none cursor-pointer transition-[background-color,color] duration-[var(--duration-fast)] hover:bg-background-muted hover:text-foreground focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-foreground focus-visible:outline-offset-2 motion-reduce:transition-none",
+        className,
+      )}
+      aria-label="닫기"
+      {...props}
+    >
+      {children ?? "×"}
+    </BaseDialog.Close>
+  );
+}
+
+export function DialogFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cx(
+        "flex items-center justify-end gap-[var(--space-2)] pt-[var(--space-4)] border-t border-border mt-auto",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export interface DialogContentProps
+  extends WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseDialog.Popup>> {
+  container?: React.ComponentPropsWithoutRef<typeof BaseDialog.Portal>["container"];
+}
+
+export const DialogContent = React.forwardRef<HTMLDivElement, DialogContentProps>(
+  function DialogContent({ className, children, container, ...props }, ref) {
+    return (
+      <BaseDialog.Portal container={container}>
+        <BaseDialog.Backdrop className="fixed inset-0 z-[var(--z-overlay)] bg-black/25 backdrop-blur-md transition-opacity duration-[var(--duration-slow)] motion-reduce:transition-none data-[starting-style]:opacity-0 data-[ending-style]:opacity-0" />
+        <BaseDialog.Popup
+          ref={ref}
+          className={cx(
+            "fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 z-[var(--z-modal)] flex flex-col w-[calc(100%-2rem)] max-w-md max-h-[calc(100dvh-4rem)] p-[var(--space-6)] bg-background text-foreground border border-border rounded-[var(--radius)] shadow-[var(--shadow-xl)] outline-none overflow-y-auto transition-[opacity,transform] duration-[var(--duration-slow)] motion-reduce:transition-none data-[starting-style]:opacity-0 data-[starting-style]:translate-y-[calc(-50%+0.5rem)] data-[starting-style]:scale-[0.97] data-[ending-style]:opacity-0 data-[ending-style]:translate-y-[calc(-50%+0.25rem)] data-[ending-style]:scale-[0.98] motion-reduce:data-[starting-style]:translate-y-[-50%] motion-reduce:data-[starting-style]:scale-100 motion-reduce:data-[ending-style]:translate-y-[-50%] motion-reduce:data-[ending-style]:scale-100 focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-foreground focus-visible:outline-offset-2",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </BaseDialog.Popup>
+      </BaseDialog.Portal>
+    );
+  },
+);
+
+export const DialogTitle = React.forwardRef<
+  HTMLHeadingElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseDialog.Title>>
+>(function DialogTitle({ className, ...props }, ref) {
+  return (
+    <BaseDialog.Title
+      ref={ref}
+      className={cx(
+        "m-0 mb-[var(--space-1)] font-semibold text-[length:var(--text-lg)] leading-snug",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const DialogDescription = React.forwardRef<
+  HTMLParagraphElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseDialog.Description>>
+>(function DialogDescription({ className, ...props }, ref) {
+  return (
+    <BaseDialog.Description
+      ref={ref}
+      className={cx(
+        "m-0 mb-[var(--space-5)] text-foreground-muted text-[length:var(--text-sm)] leading-normal",
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/data/registry/react/components/dropdown-menu/index.tailwind.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import * as React from "react";
+import { Menu as BaseMenu } from "@base-ui/react/menu";
+
+type WithStringClassName<T> = Omit<T, "className"> & { className?: string };
+
+function cx(...args: (string | undefined | false | null)[]) {
+  return args.filter(Boolean).join(" ");
+}
+
+const itemBase =
+  "relative flex items-center gap-[var(--space-2)] py-2 px-3 rounded-[calc(var(--radius)-2px)] cursor-pointer outline-none select-none transition-colors duration-[80ms] data-[highlighted]:bg-background-muted hover:bg-background-muted data-[disabled]:opacity-[var(--opacity-disabled)] data-[disabled]:pointer-events-none motion-reduce:transition-none";
+const itemCheck = "pl-7";
+
+export const DropdownMenu = BaseMenu.Root;
+
+export const DropdownMenuTrigger = React.forwardRef<
+  HTMLButtonElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.Trigger>>
+>(function DropdownMenuTrigger({ className, ...props }, ref) {
+  return (
+    <BaseMenu.Trigger
+      ref={ref}
+      className={cx(
+        "font-[inherit] cursor-pointer focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-foreground focus-visible:outline-offset-2",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export interface DropdownMenuContentProps
+  extends WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.Popup>> {
+  side?: "top" | "right" | "bottom" | "left";
+  align?: "start" | "center" | "end";
+  sideOffset?: number;
+  container?: React.ComponentPropsWithoutRef<typeof BaseMenu.Portal>["container"];
+}
+
+export const DropdownMenuContent = React.forwardRef<HTMLDivElement, DropdownMenuContentProps>(
+  function DropdownMenuContent(
+    { className, children, side, align, sideOffset = 6, container, ...props },
+    ref,
+  ) {
+    return (
+      <BaseMenu.Portal container={container}>
+        <BaseMenu.Positioner
+          className="outline-none z-[var(--z-dropdown)]"
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+        >
+          <BaseMenu.Popup
+            ref={ref}
+            className={cx(
+              "min-w-40 max-h-[min(24rem,var(--available-height,24rem))] overflow-y-auto p-[var(--space-1)] bg-background text-foreground border border-border rounded-[var(--radius)] shadow-[0_4px_6px_-1px_rgba(0,0,0,0.08),0_2px_4px_-2px_rgba(0,0,0,0.05)] text-[length:var(--text-sm)] origin-[var(--transform-origin)] animate-[sh-ui-dm-in_140ms_ease-out] data-[ending-style]:animate-[sh-ui-dm-out_100ms_ease-in_forwards] outline-none motion-reduce:animate-none motion-reduce:data-[ending-style]:animate-none",
+              className,
+            )}
+            {...props}
+          >
+            {children}
+          </BaseMenu.Popup>
+        </BaseMenu.Positioner>
+      </BaseMenu.Portal>
+    );
+  },
+);
+
+export const DropdownMenuItem = React.forwardRef<
+  HTMLDivElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.Item>>
+>(function DropdownMenuItem({ className, ...props }, ref) {
+  return <BaseMenu.Item ref={ref} className={cx(itemBase, className)} {...props} />;
+});
+
+export interface DropdownMenuCheckboxItemProps
+  extends WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.CheckboxItem>> {}
+
+export const DropdownMenuCheckboxItem = React.forwardRef<
+  HTMLDivElement,
+  DropdownMenuCheckboxItemProps
+>(function DropdownMenuCheckboxItem({ className, children, ...props }, ref) {
+  return (
+    <BaseMenu.CheckboxItem ref={ref} className={cx(itemBase, itemCheck, className)} {...props}>
+      <span className="absolute left-2 inline-flex items-center justify-center w-4 h-4 text-foreground" aria-hidden>
+        <BaseMenu.CheckboxItemIndicator>
+          <CheckIcon />
+        </BaseMenu.CheckboxItemIndicator>
+      </span>
+      <span className="flex-1 min-w-0 overflow-hidden text-ellipsis whitespace-nowrap">{children}</span>
+    </BaseMenu.CheckboxItem>
+  );
+});
+
+export const DropdownMenuRadioGroup = BaseMenu.RadioGroup;
+
+export interface DropdownMenuRadioItemProps
+  extends WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.RadioItem>> {}
+
+export const DropdownMenuRadioItem = React.forwardRef<
+  HTMLDivElement,
+  DropdownMenuRadioItemProps
+>(function DropdownMenuRadioItem({ className, children, ...props }, ref) {
+  return (
+    <BaseMenu.RadioItem ref={ref} className={cx(itemBase, itemCheck, className)} {...props}>
+      <span className="absolute left-2 inline-flex items-center justify-center w-4 h-4 text-foreground" aria-hidden>
+        <BaseMenu.RadioItemIndicator>
+          <DotIcon />
+        </BaseMenu.RadioItemIndicator>
+      </span>
+      <span className="flex-1 min-w-0 overflow-hidden text-ellipsis whitespace-nowrap">{children}</span>
+    </BaseMenu.RadioItem>
+  );
+});
+
+export const DropdownMenuGroup = React.forwardRef<
+  HTMLDivElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.Group>>
+>(function DropdownMenuGroup({ className, ...props }, ref) {
+  return <BaseMenu.Group ref={ref} className={cx("p-0", className)} {...props} />;
+});
+
+export const DropdownMenuLabel = React.forwardRef<
+  HTMLDivElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.GroupLabel>>
+>(function DropdownMenuLabel({ className, ...props }, ref) {
+  return (
+    <BaseMenu.GroupLabel
+      ref={ref}
+      className={cx(
+        "py-[var(--space-2)] px-[var(--space-2)] pb-[var(--space-1)] text-[length:var(--text-xs)] font-semibold text-foreground-muted uppercase tracking-[0.04em]",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const DropdownMenuSeparator = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function DropdownMenuSeparator({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        role="separator"
+        aria-orientation="horizontal"
+        className={cx("h-px bg-border my-[var(--space-1)]", className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export const DropdownMenuSub = BaseMenu.SubmenuRoot;
+
+export const DropdownMenuSubTrigger = React.forwardRef<
+  HTMLDivElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenu.SubmenuTrigger>>
+>(function DropdownMenuSubTrigger({ className, children, ...props }, ref) {
+  return (
+    <BaseMenu.SubmenuTrigger
+      ref={ref}
+      className={cx(itemBase, "data-[popup-open]:bg-background-muted", className)}
+      {...props}
+    >
+      <span className="flex-1 min-w-0 overflow-hidden text-ellipsis whitespace-nowrap">{children}</span>
+      <span className="inline-flex items-center justify-center ml-auto text-foreground-muted" aria-hidden>
+        <ChevronRightIcon />
+      </span>
+    </BaseMenu.SubmenuTrigger>
+  );
+});
+
+export const DropdownMenuSubContent = DropdownMenuContent;
+
+function CheckIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden>
+      <path d="M3.5 8.5l3 3 6-7" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+function DotIcon() {
+  return <svg width="8" height="8" viewBox="0 0 8 8" fill="currentColor" aria-hidden><circle cx="4" cy="4" r="3" /></svg>;
+}
+
+function ChevronRightIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden>
+      <path d="M6 4l4 4-4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+if (typeof document !== "undefined" && !document.querySelector("style[data-sh-ui-dm]")) {
+  const style = document.createElement("style");
+  style.setAttribute("data-sh-ui-dm", "");
+  style.textContent = `
+@keyframes sh-ui-dm-in { from { opacity: 0; transform: scale(0.96); } to { opacity: 1; transform: scale(1); } }
+@keyframes sh-ui-dm-out { from { opacity: 1; transform: scale(1); } to { opacity: 0; transform: scale(0.96); } }
+  `;
+  document.head.appendChild(style);
+}

package/data/registry/react/components/label/index.tailwind.tsx

@@ -0,0 +1,78 @@
+import * as React from "react";
+
+export interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  /**
+   * 필수 필드 표시. `true`면 LabelTitle 뒤에 `*` 표시.
+   * (Tailwind 변종은 plain 변종의 `:has()` 인접 셀렉터 자동 감지를 지원하지 않음 — 명시적으로 prop 사용.)
+   *
+   * @default false
+   */
+  isRequired?: boolean;
+}
+
+function cx(...args: (string | undefined | false)[]) {
+  return args.filter(Boolean).join(" ");
+}
+
+export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
+  ({ className, children, isRequired, ...props }, ref) => (
+    <label
+      ref={ref}
+      className={cx(
+        "flex flex-col gap-0.5 text-[length:var(--text-sm)] font-medium leading-snug text-foreground cursor-pointer select-none not-has-[[data-sh-ui-label-part]]:block",
+        // 필수 표시 — title 이 있으면 title 뒤, 없으면 label 뒤에 * 부착
+        isRequired &&
+          "has-[[data-sh-ui-label-part='title']]:[&>[data-sh-ui-label-part='title']]:after:content-['_*'] has-[[data-sh-ui-label-part='title']]:[&>[data-sh-ui-label-part='title']]:after:text-danger has-[[data-sh-ui-label-part='title']]:[&>[data-sh-ui-label-part='title']]:after:font-semibold not-has-[[data-sh-ui-label-part='title']]:after:content-['_*'] not-has-[[data-sh-ui-label-part='title']]:after:text-danger not-has-[[data-sh-ui-label-part='title']]:after:font-semibold",
+        className,
+      )}
+      data-required={isRequired || undefined}
+      {...props}
+    >
+      {children}
+    </label>
+  ),
+);
+Label.displayName = "Label";
+
+export function LabelTitle({ className, ...props }: React.HTMLAttributes<HTMLSpanElement>) {
+  return (
+    <span
+      data-sh-ui-label-part="title"
+      className={cx("font-semibold text-[length:var(--text-sm)] text-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function LabelSubtitle({ className, ...props }: React.HTMLAttributes<HTMLSpanElement>) {
+  return (
+    <span
+      data-sh-ui-label-part="subtitle"
+      className={cx("font-normal text-[0.8125rem] text-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function LabelDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return (
+    <p
+      data-sh-ui-label-part="description"
+      className={cx("m-0 font-normal text-[0.8125rem] leading-snug text-foreground-muted", className)}
+      {...props}
+    />
+  );
+}
+
+export function LabelCaption({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return (
+    <p
+      data-sh-ui-label-part="caption"
+      className={cx(
+        "m-0 font-normal text-[length:var(--text-xs)] leading-tight text-[var(--foreground-subtle,var(--foreground-muted))] opacity-75",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/data/registry/react/components/menubar/index.tailwind.tsx

@@ -0,0 +1,32 @@
+import * as React from "react";
+import { Menubar as BaseMenubar } from "@base-ui/react/menubar";
+
+type WithStringClassName<T> = Omit<T, "className"> & { className?: string };
+
+function cx(...args: (string | undefined | false | null)[]) {
+  return args.filter(Boolean).join(" ");
+}
+
+/**
+ * 상단 앱 메뉴바 (Tailwind 변종). DropdownMenu 와 함께 사용 — DropdownMenu 의
+ * Tailwind 변종이 plain 으로 fallback 된 경우 트리거 스타일은 plain CSS 로 적용됨.
+ *
+ * Tailwind 변종에서는 메뉴바 안의 DropdownMenu 트리거 재지정을 utility 로 표현하기
+ * 어려워 (자식 컴포넌트 클래스 의존), 메뉴바 자체의 외형만 utility 로 변환.
+ * 트리거 스타일링이 필요하면 사용자가 trigger 에 직접 className 부여.
+ */
+export const Menubar = React.forwardRef<
+  HTMLDivElement,
+  WithStringClassName<React.ComponentPropsWithoutRef<typeof BaseMenubar>>
+>(function Menubar({ className, ...props }, ref) {
+  return (
+    <BaseMenubar
+      ref={ref}
+      className={cx(
+        "inline-flex items-center gap-[var(--space-1)] p-[var(--space-1)] bg-background border border-border rounded-[var(--radius)] shadow-[0_1px_2px_rgba(0,0,0,0.04)]",
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/data/registry/react/components/numeric-input/index.tailwind.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import * as React from "react";
+
+function cx(...args: (string | undefined | null | false)[]) {
+  return args.filter(Boolean).join(" ");
+}
+
+export interface NumericInputProps
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    "value" | "defaultValue" | "onChange" | "type" | "min" | "max" | "step"
+  > {
+  value?: number;
+  defaultValue?: number;
+  onValueChange?: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: React.ReactNode;
+}
+
+const inputClasses =
+  "w-10 px-1 py-0.5 font-mono text-[length:var(--text-xs)] leading-tight text-right border border-transparent rounded-[calc(var(--radius)-4px)] bg-transparent text-foreground appearance-none [-moz-appearance:textfield] transition-[border-color,background-color] duration-[var(--duration-fast)] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none [&::-webkit-inner-spin-button]:m-0 [&::-webkit-outer-spin-button]:m-0 hover:not-disabled:not-focus:border-border focus:outline-none focus:border-foreground focus:bg-background focus-visible:outline-none focus-visible:border-foreground disabled:cursor-not-allowed disabled:opacity-[var(--opacity-disabled)]";
+
+export const NumericInput = React.forwardRef<HTMLInputElement, NumericInputProps>(
+  (
+    { value, defaultValue, onValueChange, min, max, step = 1, unit, className, onFocus, onBlur, onKeyDown, ...props },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<number>(defaultValue ?? 0);
+    const current = isControlled ? value! : internal;
+
+    const [buffer, setBuffer] = React.useState<string>(() => String(current));
+    const focusedRef = React.useRef(false);
+
+    React.useEffect(() => {
+      if (!focusedRef.current) setBuffer(String(current));
+    }, [current]);
+
+    const clamp = (n: number) => {
+      let v = n;
+      if (min !== undefined && v < min) v = min;
+      if (max !== undefined && v > max) v = max;
+      return v;
+    };
+
+    const commit = (n: number): number => {
+      const c = clamp(n);
+      if (!isControlled) setInternal(c);
+      onValueChange?.(c);
+      return c;
+    };
+
+    return (
+      <span className="inline-flex items-baseline gap-[2px] min-w-[3rem] justify-end">
+        <input
+          ref={ref}
+          type="text"
+          inputMode="decimal"
+          className={cx(inputClasses, className)}
+          value={buffer}
+          onChange={(e) => {
+            const raw = e.target.value;
+            setBuffer(raw);
+            if (raw === "" || raw === "-" || raw === "." || raw === "-.") return;
+            const n = Number(raw);
+            if (Number.isFinite(n)) commit(n);
+          }}
+          onFocus={(e) => {
+            focusedRef.current = true;
+            const t = e.currentTarget;
+            setTimeout(() => t.select(), 0);
+            onFocus?.(e);
+          }}
+          onBlur={(e) => {
+            focusedRef.current = false;
+            const n = Number(buffer);
+            if (buffer !== "" && Number.isFinite(n)) {
+              const c = commit(n);
+              setBuffer(String(c));
+            } else {
+              setBuffer(String(current));
+            }
+            onBlur?.(e);
+          }}
+          onKeyDown={(e) => {
+            if (e.key === "ArrowUp") {
+              e.preventDefault();
+              const next = commit(current + step);
+              setBuffer(String(next));
+            } else if (e.key === "ArrowDown") {
+              e.preventDefault();
+              const next = commit(current - step);
+              setBuffer(String(next));
+            } else if (e.key === "Enter") {
+              e.currentTarget.blur();
+            }
+            onKeyDown?.(e);
+          }}
+          {...props}
+        />
+        {unit !== undefined && unit !== "" && (
+          <span className="font-mono text-[length:var(--text-xs)] text-foreground-muted" aria-hidden>
+            {unit}
+          </span>
+        )}
+      </span>
+    );
+  },
+);
+NumericInput.displayName = "NumericInput";

package/data/registry/react/components/page-toc/index.tailwind.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import * as React from "react";
+
+export type HeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+export interface PageTOCProps {
+  containerSelector?: string;
+  routeKey?: string;
+  headerOffsetRem?: number;
+  label?: React.ReactNode;
+  levels?: HeadingLevel[];
+  excludeSelector?: string;
+  className?: string;
+}
+
+const slugify = (text: string): string =>
+  text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w\s가-힣-]/g, "")
+    .replace(/\s+/g, "-");
+
+interface TocItem {
+  id: string;
+  text: string;
+  level: HeadingLevel;
+}
+
+const cx = (...args: (string | undefined | false | null)[]) =>
+  args.filter(Boolean).join(" ");
+
+const linkBase =
+  "block px-2 py-1 rounded-[calc(var(--radius)-4px)] text-foreground-muted no-underline leading-snug transition-[color,background-color] duration-[var(--duration-fast)] hover:text-foreground hover:bg-background-subtle focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-foreground focus-visible:outline-offset-2 data-[active=true]:text-foreground data-[active=true]:font-semibold data-[active=true]:bg-background-subtle motion-reduce:transition-none";
+
+export function PageTOC({
+  containerSelector = "main",
+  routeKey,
+  headerOffsetRem = 5,
+  label = "On this page",
+  levels = ["h2", "h3"],
+  excludeSelector,
+  className,
+}: PageTOCProps) {
+  const [items, setItems] = React.useState<TocItem[]>([]);
+  const [activeId, setActiveId] = React.useState<string | null>(null);
+
+  const levelsKey = levels.join(",");
+  const levelsRef = React.useRef(levels);
+  levelsRef.current = levels;
+
+  React.useEffect(() => {
+    const container = document.querySelector(containerSelector);
+    if (!container) {
+      setItems([]);
+      return;
+    }
+
+    const headingSelector = levelsRef.current.join(", ");
+    let headings = Array.from(
+      container.querySelectorAll<HTMLHeadingElement>(headingSelector),
+    );
+    if (excludeSelector) {
+      headings = headings.filter((h) => !h.closest(excludeSelector));
+    }
+
+    const usedIds = new Set<string>();
+    const collected: TocItem[] = headings.map((h) => {
+      const text = h.textContent?.trim() ?? "";
+      let id = h.id || slugify(text);
+      let suffix = 2;
+      const base = id;
+      while (!id || usedIds.has(id)) {
+        id = `${base}-${suffix++}`;
+      }
+      usedIds.add(id);
+      if (!h.id) h.id = id;
+      h.style.scrollMarginTop = `${headerOffsetRem}rem`;
+      const level = h.tagName.toLowerCase() as HeadingLevel;
+      return { id, text, level };
+    });
+
+    setItems(collected);
+    if (collected.length === 0) return;
+
+    const remInPx = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    const topOffsetPx = Math.round(headerOffsetRem * remInPx);
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((e) => e.isIntersecting)
+          .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+        if (visible.length > 0) setActiveId(visible[0].target.id);
+      },
+      { rootMargin: `-${topOffsetPx}px 0px -70% 0px`, threshold: 0 },
+    );
+
+    headings.forEach((h) => observer.observe(h));
+    return () => observer.disconnect();
+  }, [containerSelector, headerOffsetRem, levelsKey, excludeSelector, routeKey]);
+
+  const handleClick = (event: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+    event.preventDefault();
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.scrollIntoView({ behavior: "smooth", block: "start" });
+    history.replaceState(null, "", `#${id}`);
+    setActiveId(id);
+  };
+
+  if (items.length === 0) return null;
+
+  const linkClassesForLevel = (level: HeadingLevel) => {
+    const num = parseInt(level.replace("h", ""), 10);
+    if (num === 3 || num === 4) return "pl-5 text-[0.8125em] text-[var(--foreground-subtle,var(--foreground-muted))]";
+    if (num >= 5) return "pl-8 text-[0.75em] text-[var(--foreground-subtle,var(--foreground-muted))]";
+    return "";
+  };
+
+  return (
+    <nav
+      className={cx(
+        "fixed top-20 right-6 w-56 max-h-[calc(100vh-7rem)] overflow-y-auto pl-4 pr-2 py-3 border-l border-border text-[0.8125rem] z-[5] max-[80rem]:hidden",
+        className,
+      )}
+      aria-label={typeof label === "string" ? label : "목차"}
+    >
+      <div className="font-semibold text-[length:var(--text-xs)] text-foreground-muted uppercase tracking-[0.04em] mb-2">
+        {label}
+      </div>
+      <ul className="list-none m-0 p-0 flex flex-col gap-0.5">
+        {items.map((item) => (
+          <li key={item.id} data-level={item.level.replace("h", "")}>
+            <a
+              href={`#${item.id}`}
+              onClick={(e) => handleClick(e, item.id)}
+              className={cx(linkBase, linkClassesForLevel(item.level))}
+              data-active={activeId === item.id ? "true" : undefined}
+              aria-current={activeId === item.id ? "true" : undefined}
+            >
+              {item.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}