sh-ui-cli 0.45.3 → 0.47.0

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

@@ -0,0 +1,174 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "@SH_UI_UTILS@";
+import styles from "./styles.module.css";
+
+export type HeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+export interface PageTOCProps {
+  /**
+   * 스캔할 컨테이너 selector. 기본 `"main"`.
+   */
+  containerSelector?: string;
+  /**
+   * 외부 신호로 TOC 재스캔. Next.js 사용 시 `usePathname()` 결과를 그대로 전달하면
+   * 라우트 변경 때마다 자동 갱신. 같은 페이지 안에서 헤딩이 동적으로 바뀌면 이 값을 갱신.
+   */
+  routeKey?: string;
+  /**
+   * sticky 헤더 아래로 헤딩이 가려지지 않도록 띄울 거리(rem). `scroll-margin-top` 으로 적용.
+   * @default 5
+   */
+  headerOffsetRem?: number;
+  /**
+   * 라벨 텍스트.
+   * @default "On this page"
+   */
+  label?: React.ReactNode;
+  /**
+   * 수집할 헤딩 레벨.
+   * @default ["h2", "h3"]
+   */
+  levels?: HeadingLevel[];
+  /**
+   * 제외할 헤딩 selector. 컨테이너 안에서 이 selector 의 자손인 헤딩은 무시.
+   * 데모 미리보기·중첩 위젯 등을 TOC 에서 빼고 싶을 때 사용.
+   */
+  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;
+}
+
+
+/**
+ * 페이지 내 자동 목차 (On this page).
+ *
+ * 컨테이너 안의 지정한 헤딩 레벨을 스캔해 자동 slugify · id 부여 · `IntersectionObserver` 로
+ * 현재 보이는 섹션을 active 표시 · 클릭 시 smooth scroll. 라우터 비종속 — `routeKey` 를
+ * 외부에서 갱신하면 재스캔된다.
+ */
+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);
+
+  // levels 가 inline 배열(["h2", "h3"]) 로 전달되면 매 렌더마다 새 참조라 useEffect 가
+  // 무한 루프에 빠짐. 내용 기반 안정 키로 비교하고, 효과 안에서는 ref 로 최신 값 사용.
+  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;
+
+  return (
+    <nav
+      className={cn(styles["page-toc"], className)}
+      aria-label={typeof label === "string" ? label : "목차"}
+    >
+      <div className={styles["page-toc__label"]}>{label}</div>
+      <ul className={styles["page-toc__list"]}>
+        {items.map((item) => (
+          <li key={item.id} data-level={item.level.replace("h", "")}>
+            <a
+              href={`#${item.id}`}
+              onClick={(e) => handleClick(e, item.id)}
+              className={styles["page-toc__link"]}
+              data-active={activeId === item.id ? "true" : undefined}
+              aria-current={activeId === item.id ? "true" : undefined}
+            >
+              {item.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

package/data/registry/react/components/page-toc/styles.module.css

@@ -0,0 +1,82 @@
+/* 페이지 내 목차 (On this page).
+   기본은 우측 고정 레일 — 좁은 뷰포트(<80rem)에서는 자동 숨김. 다른 배치(예: 본문 상단 inline)
+   가 필요하면 className override 또는 자체 wrapper 로 위치 재정의. */
+.page-toc {
+  position: fixed;
+  top: 5rem;
+  right: 1.5rem;
+  width: 14rem;
+  max-height: calc(100vh - 7rem);
+  overflow-y: auto;
+  padding: 0.75rem 0.5rem 0.75rem 1rem;
+  border-left: 1px solid var(--border);
+  font-size: 0.8125rem;
+  z-index: 5;
+}
+
+.page-toc__label {
+  font-weight: 600;
+  font-size: 0.75rem;
+  color: var(--foreground-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 0.5rem;
+}
+
+.page-toc__list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.page-toc__list > li[data-level="3"] .page-toc__link,
+.page-toc__list > li[data-level="4"] .page-toc__link {
+  padding-left: 1.25rem;
+  font-size: 0.8125em;
+  color: var(--foreground-subtle, var(--foreground-muted));
+}
+.page-toc__list > li[data-level="5"] .page-toc__link,
+.page-toc__list > li[data-level="6"] .page-toc__link {
+  padding-left: 2rem;
+  font-size: 0.75em;
+  color: var(--foreground-subtle, var(--foreground-muted));
+}
+
+.page-toc__link {
+  display: block;
+  padding: 0.25rem 0.5rem;
+  border-radius: calc(var(--radius) - 4px);
+  color: var(--foreground-muted);
+  text-decoration: none;
+  line-height: 1.4;
+  transition: color var(--duration-fast), background-color var(--duration-fast);
+}
+.page-toc__link:hover {
+  color: var(--foreground);
+  background: var(--background-subtle);
+}
+.page-toc__link:focus-visible {
+  outline: var(--border-width-strong) solid var(--foreground);
+  outline-offset: 2px;
+}
+.page-toc__link[data-active="true"] {
+  color: var(--foreground);
+  font-weight: 600;
+  background: var(--background-subtle);
+}
+
+/* 좁은 뷰포트에선 우측 레일 숨김 — 본문 너비를 침범하지 않도록 */
+@media (max-width: 80rem) {
+  .page-toc {
+    display: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .page-toc__link {
+    transition: none;
+  }
+}

package/data/registry/react/components/pagination/index.module.tsx

@@ -0,0 +1,269 @@
+import * as React from "react";
+import styles from "./styles.module.css";
+
+
+import { cn } from "@SH_UI_UTILS@";
+/* ───────── Pagination (nav) ─────────
+ * 시맨틱: <nav aria-label="Pagination"><ul>...</ul></nav>.
+ * 현재 페이지 링크에 aria-current="page"를 부여해 스크린리더가 위치를 읽게 한다.
+ */
+
+/**
+ * 페이지 분할 내비게이션의 시맨틱 컨테이너(`<nav aria-label="Pagination">`).
+ * 자식 구조: PaginationContent > PaginationItem × n > PaginationLink/Previous/Next/Ellipsis.
+ */
+export const Pagination = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(function Pagination({ className, ...props }, ref) {
+  return (
+    <nav
+      ref={ref}
+      aria-label="Pagination"
+      className={cn(styles.pagination, className)}
+      {...props}
+    />
+  );
+});
+
+/* ───────── Content (ul) ───────── */
+
+/** 페이지 항목들을 담는 정렬되지 않은 리스트(`<ul>`). */
+export const PaginationContent = React.forwardRef<
+  HTMLUListElement,
+  React.HTMLAttributes<HTMLUListElement>
+>(function PaginationContent({ className, ...props }, ref) {
+  return (
+    <ul
+      ref={ref}
+      className={cn(styles.pagination__content, className)}
+      {...props}
+    />
+  );
+});
+
+/* ───────── Item (li) ───────── */
+
+/** 한 페이지 슬롯(`<li>`). PaginationLink/Previous/Next/Ellipsis를 자식으로 둔다. */
+export const PaginationItem = React.forwardRef<
+  HTMLLIElement,
+  React.LiHTMLAttributes<HTMLLIElement>
+>(function PaginationItem({ className, ...props }, ref) {
+  return (
+    <li
+      ref={ref}
+      className={cn(styles.pagination__item, className)}
+      {...props}
+    />
+  );
+});
+
+/* ───────── Link ─────────
+ * 숫자 페이지 링크. isActive일 때 aria-current="page" + 시각 강조.
+ */
+
+export interface PaginationLinkProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * 현재 페이지 표시. `true`면 `aria-current="page"`가 자동 부여되고 시각적으로 강조된다.
+   * @default false
+   */
+  isActive?: boolean;
+  /**
+   * 크기.
+   * - `sm` — 컴팩트
+   * - `md` — 일반 (기본)
+   *
+   * @default "md"
+   */
+  size?: "sm" | "md";
+}
+
+/**
+ * 숫자 페이지 링크. `isActive`이면 `aria-current="page"`가 자동 부여되어
+ * 스크린리더가 현재 위치를 읽는다.
+ */
+export const PaginationLink = React.forwardRef<
+  HTMLAnchorElement,
+  PaginationLinkProps
+>(function PaginationLink(
+  { className, isActive, size = "md", ...props },
+  ref,
+) {
+  return (
+    <a
+      ref={ref}
+      aria-current={isActive ? "page" : undefined}
+      data-active={isActive ? "" : undefined}
+      data-size={size}
+      className={cn(styles.pagination__link, className)}
+      {...props}
+    />
+  );
+});
+
+/* ───────── Previous / Next ─────────
+ * 아이콘 + 레이블. 레이블이 없는 아이콘 버튼에는 aria-label로 의미 전달.
+ */
+
+/** "이전 페이지" 링크. 화살표 아이콘과 라벨이 함께 렌더되며 `aria-label`이 자동 부여된다. */
+export const PaginationPrevious = React.forwardRef<
+  HTMLAnchorElement,
+  PaginationLinkProps
+>(function PaginationPrevious({ className, children, ...props }, ref) {
+  return (
+    <PaginationLink
+      ref={ref}
+      aria-label="이전 페이지"
+      className={cn(styles.pagination__nav, className)}
+      {...props}
+    >
+      <ChevronLeftIcon />
+      {children ?? <span>이전</span>}
+    </PaginationLink>
+  );
+});
+
+/** "다음 페이지" 링크. */
+export const PaginationNext = React.forwardRef<
+  HTMLAnchorElement,
+  PaginationLinkProps
+>(function PaginationNext({ className, children, ...props }, ref) {
+  return (
+    <PaginationLink
+      ref={ref}
+      aria-label="다음 페이지"
+      className={cn(styles.pagination__nav, className)}
+      {...props}
+    >
+      {children ?? <span>다음</span>}
+      <ChevronRightIcon />
+    </PaginationLink>
+  );
+});
+
+/* ───────── Ellipsis — 생략 표시 ───────── */
+
+/** 페이지 사이 생략을 표현하는 점 3개. 시각만 표현하고 스크린리더에는 무시된다. */
+export const PaginationEllipsis = React.forwardRef<
+  HTMLSpanElement,
+  React.HTMLAttributes<HTMLSpanElement>
+>(function PaginationEllipsis({ className, ...props }, ref) {
+  return (
+    <span
+      ref={ref}
+      role="presentation"
+      aria-hidden="true"
+      className={cn(styles.pagination__ellipsis, className)}
+      {...props}
+    >
+      <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden>
+        <circle cx="3" cy="8" r="1.25" />
+        <circle cx="8" cy="8" r="1.25" />
+        <circle cx="13" cy="8" r="1.25" />
+      </svg>
+      <span className={styles.pagination__sr}>더 많은 페이지</span>
+    </span>
+  );
+});
+
+/* ───────── 페이지 범위 유틸 ─────────
+ * 현재 페이지 주변 siblings개 + 양 끝 1개 + 필요한 곳에 "dots"를 넣어
+ * 렌더할 토큰 배열을 돌려준다.
+ *
+ * 예: page=5, totalPages=10, siblings=1 → [1, "dots", 4, 5, 6, "dots", 10]
+ *
+ * page·totalPages는 1-based를 가정한다.
+ */
+
+export type PaginationToken = number | "dots";
+
+/**
+ * 1-based `page`/`totalPages`로부터 렌더할 토큰 배열을 만든다.
+ * 양 끝과 현재 주변 `siblings`개를 보여주고, 끊긴 구간엔 `"dots"`를 넣어준다.
+ *
+ * @param args.page - 1-based 현재 페이지.
+ * @param args.siblings - 현재 페이지 양옆에 보일 페이지 개수.
+ * @returns 렌더 토큰 배열. 숫자 또는 문자열 `"dots"`로 구성.
+ * @example
+ * getPaginationRange({ page: 5, totalPages: 10, siblings: 1 })
+ * // [1, "dots", 4, 5, 6, "dots", 10]
+ */
+export function getPaginationRange({
+  page,
+  totalPages,
+  siblings = 1,
+}: {
+  /** 1-based 현재 페이지. */
+  page: number;
+  /** 전체 페이지 수. */
+  totalPages: number;
+  /**
+   * 현재 페이지 양옆에 보일 페이지 개수.
+   * @default 1
+   */
+  siblings?: number;
+}): PaginationToken[] {
+  if (totalPages <= 0) return [];
+
+  // 끝점 2개(첫/마지막) + 현재 주변 (2*siblings + 1) + dots 2개가 총 페이지 수보다 크거나 같으면
+  // 생략 없이 전부 보여준다.
+  const totalSlots = siblings * 2 + 5;
+  if (totalPages <= totalSlots) {
+    return range(1, totalPages);
+  }
+
+  const leftSibling = Math.max(page - siblings, 1);
+  const rightSibling = Math.min(page + siblings, totalPages);
+
+  const showLeftDots = leftSibling > 2;
+  const showRightDots = rightSibling < totalPages - 1;
+
+  // 왼쪽만 닫혀있음 → [1 ... right side]
+  if (!showLeftDots && showRightDots) {
+    const leftCount = 3 + 2 * siblings;
+    return [...range(1, leftCount), "dots", totalPages];
+  }
+
+  // 오른쪽만 닫혀있음 → [1 ... left side]
+  if (showLeftDots && !showRightDots) {
+    const rightCount = 3 + 2 * siblings;
+    return [1, "dots", ...range(totalPages - rightCount + 1, totalPages)];
+  }
+
+  // 양쪽 모두 생략
+  return [1, "dots", ...range(leftSibling, rightSibling), "dots", totalPages];
+}
+
+function range(start: number, end: number): number[] {
+  const length = end - start + 1;
+  return Array.from({ length }, (_, i) => start + i);
+}
+
+function ChevronLeftIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden>
+      <path
+        d="M10 4l-4 4 4 4"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function ChevronRightIcon() {
+  return (
+    <svg width="14" height="14" 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>
+  );
+}

package/data/registry/react/components/pagination/styles.module.css

@@ -0,0 +1,105 @@
+.pagination {
+  display: flex;
+  justify-content: center;
+  font-size: var(--text-sm);
+  color: var(--foreground);
+}
+
+.pagination__content {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.25rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.pagination__item {
+  display: inline-flex;
+  align-items: center;
+}
+
+.pagination__link {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
+  min-width: 2.25rem;
+  height: 2.25rem;
+  padding: 0 0.75rem;
+  border-radius: calc(var(--radius) - 2px);
+  border: var(--border-width) solid transparent;
+  background: transparent;
+  color: var(--foreground);
+  text-decoration: none;
+  transition:
+    background-color var(--duration-fast),
+    border-color var(--duration-fast),
+    color var(--duration-fast);
+  cursor: pointer;
+  user-select: none;
+}
+
+.pagination__link[data-size="sm"] {
+  min-width: 2rem;
+  height: 2rem;
+  padding: 0 0.5rem;
+}
+
+.pagination__link:hover {
+  background: var(--background-muted);
+}
+
+.pagination__link:focus-visible {
+  outline: var(--border-width-strong) solid var(--foreground);
+  outline-offset: 2px;
+}
+
+.pagination__link[data-active] {
+  background: var(--foreground);
+  color: var(--background);
+  font-weight: var(--weight-medium);
+}
+
+.pagination__link[data-active]:hover {
+  background: var(--foreground);
+  opacity: 0.9;
+}
+
+.pagination__link[aria-disabled="true"],
+.pagination__link[data-disabled] {
+  pointer-events: none;
+  opacity: 0.45;
+}
+
+.pagination__nav {
+  padding: 0 0.625rem;
+}
+
+.pagination__ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  color: var(--foreground-muted);
+}
+
+.pagination__sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pagination__link {
+    transition: none;
+  }
+}