import type { ReactNode, Ref } from "react";
import { cx } from "../../utils";

export interface FoxHeadingGroupProps {
  /** 구역 제목. 화면 제목(`FoxPageHeader`)이 아니라 그 아래 구역의 이름이다. */
  title: ReactNode;
  /**
   * 제목을 그릴 태그. 한 화면에 여러 구역이 서면 문서 구조가 어긋나지 않게 단계를 고른다.
   * 화면 제목은 `FoxPageHeader`가 `<h1>`으로 그리므로 여기 기본은 `h2`다.
   */
  as?: "h2" | "h3" | "h4";
  /** 제목 아래 한 줄 설명. 넘기지 않으면 영역을 그리지 않는다. */
  description?: ReactNode;
  /** 제목 오른쪽 자리. 보통 버튼이다. */
  actions?: ReactNode;
  /** 참이면 렌더하지 않는다(DOM에 남지 않는다). */
  hidden?: boolean;
  /** 배치 조정용. */
  className?: string;
  ref?: Ref<HTMLDivElement>;
}

/**
 * @fox 구역 머리말 — 시안: 관리자페이지(QsFVFFUKGH68xAPVkF3SJ9) heading-group (3002:7177)
 *
 * 한 화면 안에서 목록·표 같은 구역을 이름 짓는다. `FoxPageHeader`와 역할이 다르다 — 그쪽은
 * 화면에 하나뿐인 제목(`<h1>`)과 현재 위치를 갖고, 이쪽은 화면 안에 여럿 설 수 있다.
 * 그래서 제목 태그를 `as`로 고를 수 있고 breadcrumb이 없다.
 *
 * 아래 여백은 이 조각이 갖는다(시안 spacing/bottom/md) — 뒤따르는 도구 줄·표가 간격을 따로
 * 두지 않아도 되게 하려는 것이고, `FoxPageHeader`와 같은 규칙이다.
 *
 * 상호작용이 없어 `"use client"`가 아니다 — 서버 컴포넌트로 렌더된다.
 *
 * ⚠️ 스타일은 이 파일이 import하지 않는다 — 호스트 앱이 `@use "@fox/styles/components"`
 * (또는 개별 파티셜)로 한 번 불러와야 한다.
 */
export function FoxHeadingGroup({
  title,
  as: Tag = "h2",
  description,
  actions,
  hidden = false,
  className,
  ref,
}: FoxHeadingGroupProps) {
  if (hidden) {
    return null;
  }

  return (
    <div ref={ref} className={cx("fox-heading-group", className)}>
      <div className="fox-heading-group__text">
        <div className="fox-heading-group__heading">
          <Tag className="fox-heading-group__title">{title}</Tag>
        </div>
        {description && (
          <p className="fox-heading-group__description">{description}</p>
        )}
      </div>
      {actions && <div className="fox-heading-group__actions">{actions}</div>}
    </div>
  );
}