PageToolbar

검색, 필터와 보기 조작을 영향을 받는 데이터 가까이에 둡니다.

목적

PageToolbar는 검색, 필터, 보기 방식, 새로고침처럼 바로 아래 데이터에 영향을 주는 조작을 데이터 가까이에 둔다. 페이지 전체의 생성·발행 행동과 데이터 범위 조작을 분리해 사용자가 무엇이 바뀌는지 예측하게 한다.

선택 기준

목록, table, chart의 범위나 표현을 바꾸는 controls에 사용한다.
페이지의 주 생성 행동은 PageHeader.actions에 둔다.
작은 섹션 하나에만 적용되는 조작은 해당 Section.actions를 검토한다.
조작이 하나뿐이고 데이터와의 관계가 명확하면 별도 toolbar가 필요하지 않을 수 있다.

구조

title: 현재 데이터 영역의 이름
description: 범위, 갱신 기준 또는 조작의 영향
children: 결과 개수, 활성 필터 요약 같은 title 아래 추가 정보
controls: 검색, 필터, 정렬, 보기 전환, 새로고침

변형과 크기

별도 variant와 size prop은 없다.
아래 border로 데이터 frame의 시작을 구분한다.
작은 화면에서는 세로로, 큰 화면에서는 title 영역과 controls가 양쪽에 정렬된다.
controls는 전체 폭에서 줄바꿈할 수 있다.

상태와 동작

검색과 필터 상태는 URL 또는 route state에 보존해 상세에서 돌아와도 유지한다.
controls 변경 후 결과 개수와 로딩 상태를 데이터 영역 가까이 알린다.
새로고침은 현재 필터를 초기화하지 않는다.
자동 갱신이 있으면 활성 여부와 마지막 갱신 시각을 설명한다.
비동기 검색은 이전 결과를 무조건 지우기보다 갱신 중 상태를 표시해 맥락을 보존한다.

콘텐츠

title은 필터가 아니라 실행 기록, 검토할 항목처럼 데이터 대상을 말한다.
description에는 데이터 기간이나 범위를 우선한다.
검색 placeholder는 검색 가능한 필드를 구체적으로 말한다.
활성 필터는 control 값만으로 충분하지 않으면 읽을 수 있는 요약을 제공한다.
controls에 서로 같은 결과를 만드는 중복 행동을 두지 않는다.

접근성

toolbar 자체는 일반 div다. 필요하면 role="search", aria-label 같은 표준 속성을 전달해 영역 목적을 설명한다.
title이 있으면 데이터 table 또는 결과 영역과 aria-labelledby로 연결하는 구성을 제품에서 만들 수 있다.
control 순서는 사용 빈도와 작업 순서를 따른다.
icon-only control은 접근 가능한 이름과 tooltip을 제공한다.
결과 갱신은 과도하지 않은 live region으로 알린다.

좁은 화면과 긴 콘텐츠

controls는 작은 화면에서 전체 폭을 사용할 수 있다. 검색을 먼저, 자주 쓰는 필터를 다음에 둔다.
모든 고급 필터를 한 행에 압축하지 말고 sheet 또는 popover로 점진적으로 공개한다.
긴 설명이 controls를 밀어내면 기간과 범위를 더 짧은 meta로 정리한다.
선택된 필터를 숨기지 말고 요약 badge나 필터 3개처럼 현재 조건을 확인할 경로를 둔다.

공개 API

PageToolbarProps는 title을 제외한 React.HTMLAttributes<HTMLDivElement>를 확장한다.

속성	타입	기본값	설명
`title`	`ReactNode`	없음	데이터 영역 제목
`description`	`ReactNode`	없음	범위 또는 기준 설명
`controls`	`ReactNode`	없음	검색·필터·정렬 등 조작
`children`	`ReactNode`	없음	title 영역의 추가 정보
`className`	`string`	없음	toolbar 클래스
기타	`HTMLAttributes<HTMLDivElement>`	없음	표준 div 속성

예제

import { Button, Input, PageToolbar } from '@classum/dot-design-system/ui';

export function RunToolbar() {
  return (
    <PageToolbar
      title="실행 기록"
      description="최근 7일 동안 시작된 작업을 보여줘요."
      controls={
        <>
          <Input aria-label="작업 이름 검색" placeholder="작업 이름 검색" className="sm:w-64" />
          <Button variant="outline">필터</Button>
          <Button variant="ghost">새로고침</Button>
        </>
      }
    >
      <p className="mt-1 text-xs text-ink-subtle">총 128건</p>
    </PageToolbar>
  );
}

피해야 할 사용

새 항목 만들기나 발행 같은 페이지 주 행동 배치
데이터에서 멀리 떨어진 위치에 필터 배치
검색·필터 변경 시 현재 조건을 조용히 초기화
결과 갱신 중 이전 데이터를 모두 비워 깜박이게 함
작은 화면에 모든 control을 한 줄로 압축
icon-only 새로고침에 접근 가능한 이름 생략

목적