# AppBar
URL: /lynx/components/app-bar
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/app-bar.mdx

화면 상단에서 현재 화면의 제목과 탐색 액션을 보여주는 내비게이션 바 컴포넌트입니다.

Lynx Engine 최소 버전: 3.6

사용 가능 버전: @seed-design/lynx-react@0.2.0, @seed-design/lynx-css@0.2.0

## Preview

```tsx
import "./styles";

import IconBellLine from "@karrotmarket/lynx-monochrome-icon/IconBellLine";
import IconChevronLeftLine from "@karrotmarket/lynx-monochrome-icon/IconChevronLeftLine";
import { root } from "@lynx-js/react";
import { AppBar, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <view className="app-bar-preview">
        <AppBar.Root theme="cupertino">
          <AppBar.Left>
            <AppBar.IconButton accessibility-label="뒤로" icon={<IconChevronLeftLine />} />
          </AppBar.Left>
          <AppBar.Main>
            <AppBar.Title>동네생활</AppBar.Title>
          </AppBar.Main>
          <AppBar.Right>
            <AppBar.IconButton accessibility-label="알림" icon={<IconBellLine />} />
          </AppBar.Right>
        </AppBar.Root>
        <view className="app-bar-preview__content">
          <text className="app-bar-preview__status">화면 콘텐츠</text>
        </view>
      </view>
    </page>
  );
}

root.render(<Root />);
```

## Installation

- npm: npx @seed-design/cli add ui:app-bar
- pnpm: pnpm dlx @seed-design/cli add ui:app-bar
- yarn: yarn dlx @seed-design/cli add ui:app-bar
- bun: bun x @seed-design/cli add ui:app-bar

## Props

### `AppBar`

### `AppBarLeft`

### `AppBarMain`

### `AppBarRight`

### `AppBarSlot`

### `AppBarIconButton`

### `AppBarBackButton`

### `AppBarCloseButton`

## Usage

설치한 snippet은 Root와 주요 슬롯을 `AppBar`, `AppBarLeft`, `AppBarMain`, `AppBarRight`로 export 합니다. `AppBarBackButton`, `AppBarCloseButton`은 기본 아이콘만 제공하며, 실제 이동 로직은 `bindtap`으로 직접 전달합니다.

```tsx
import {
  AppBar,
  AppBarBackButton,
  AppBarLeft,
  AppBarMain,
  AppBarRight,
} from "@/components/ui/app-bar";

export function Header({ goBack }: { goBack: () => void }) {
  return (
    <AppBar>
      <AppBarLeft>
        <AppBarBackButton bindtap={goBack} />
      </AppBarLeft>
      <AppBarMain title="동네생활" />
      <AppBarRight />
    </AppBar>
  );
}
```

### Title / Subtitle

`AppBarMain`에 `title`, `subtitle`을 전달하면 내부에서 `AppBar.Title`, `AppBar.Subtitle`을 조립합니다. `subtitle`이 있으면 `layout="withSubtitle"`가 자동으로 적용됩니다.

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { AppBar, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <view className="app-bar-preview">
        <AppBar.Root theme="cupertino">
          <AppBar.Main layout="withSubtitle">
            <AppBar.Title>관심 목록</AppBar.Title>
            <AppBar.Subtitle>3개의 새 소식</AppBar.Subtitle>
          </AppBar.Main>
        </AppBar.Root>
        <view className="app-bar-preview__content">
          <text className="app-bar-preview__status">제목과 부제목을 함께 표시한 AppBar</text>
        </view>
      </view>
    </page>
  );
}

root.render(<Root />);
```

직접 슬롯을 조립하고 싶다면 `AppBarMain`의 children으로 compound 컴포넌트를 전달합니다.

```tsx
import { AppBar, AppBarMain } from "@/components/ui/app-bar";
import { AppBar as SeedAppBar } from "@seed-design/lynx-react";

export function Header() {
  return (
    <AppBar>
      <AppBarMain layout="withSubtitle">
        <SeedAppBar.Title>제목</SeedAppBar.Title>
        <SeedAppBar.Subtitle>부제목</SeedAppBar.Subtitle>
      </AppBarMain>
    </AppBar>
  );
}
```

### Left / Right Action

왼쪽과 오른쪽에는 icon button 또는 custom slot을 배치할 수 있습니다. Cupertino theme에서는 좌우 슬롯 폭을 읽어 가운데 title이 치우치지 않도록 padding을 보정합니다.

```tsx
import "./styles";

import IconChevronLeftLine from "@karrotmarket/lynx-monochrome-icon/IconChevronLeftLine";
import IconXmarkLine from "@karrotmarket/lynx-monochrome-icon/IconXmarkLine";
import { root, useState } from "@lynx-js/react";
import { AppBar, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [lastAction, setLastAction] = useState("없음");

  function handleBack() {
    "background only";
    setLastAction("뒤로");
  }

  function handleClose() {
    "background only";
    setLastAction("닫기");
  }

  return (
    <page className={seedClassName}>
      <view className="app-bar-preview">
        <AppBar.Root theme="cupertino">
          <AppBar.Left>
            <AppBar.IconButton
              accessibility-label="뒤로"
              icon={<IconChevronLeftLine />}
              bindtap={handleBack}
            />
          </AppBar.Left>
          <AppBar.Main>
            <AppBar.Title>작성하기</AppBar.Title>
          </AppBar.Main>
          <AppBar.Right>
            <AppBar.Slot>
              <text>완료</text>
            </AppBar.Slot>
            <AppBar.IconButton
              accessibility-label="닫기"
              icon={<IconXmarkLine />}
              bindtap={handleClose}
            />
          </AppBar.Right>
        </AppBar.Root>
        <view className="app-bar-preview__content">
          <text className="app-bar-preview__status">마지막 액션: {lastAction}</text>
        </view>
      </view>
    </page>
  );
}

root.render(<Root />);
```

### Accessibility

Lynx에서는 HTML ARIA 속성 대신 Lynx native 접근성 속성을 사용합니다. `AppBarIconButton`은 기본적으로 `accessibility-element={true}`와 `accessibility-traits="button"`을 적용하며, 아이콘만으로 의미를 알 수 없는 버튼에는 `accessibility-label`을 전달해야 합니다.

```tsx
import IconBellLine from "@karrotmarket/lynx-monochrome-icon/IconBellLine";

<AppBarIconButton accessibility-label="알림" icon={<IconBellLine />} />
```

`AppBarBackButton`, `AppBarCloseButton`은 각각 `"뒤로"`, `"닫기"` 라벨을 기본값으로 제공합니다.

### Theme

`theme`은 `"cupertino"` 또는 `"android"`를 사용할 수 있습니다. 명시하지 않으면 AppBar 내부에서 `SystemInfo.platform`을 읽어 Android에서는 `"android"`, 그 외 플랫폼이나 값이 없을 때는 `"cupertino"`를 사용합니다.

```tsx
<AppBar>
  <AppBarMain title="자동 theme" />
</AppBar>
```

수동으로 지정한 `theme`은 platform 기본값보다 우선합니다.

```tsx
import "./styles";

import IconChevronLeftLine from "@karrotmarket/lynx-monochrome-icon/IconChevronLeftLine";
import IconXmarkLine from "@karrotmarket/lynx-monochrome-icon/IconXmarkLine";
import { root } from "@lynx-js/react";
import { AppBar, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <view className="app-bar-preview__platforms">
        <view className="app-bar-preview__platform">
          <text className="app-bar-preview__label">Cupertino</text>
          <view className="app-bar-preview app-bar-preview--platform">
            <AppBar.Root theme="cupertino">
              <AppBar.Left>
                <AppBar.IconButton accessibility-label="뒤로" icon={<IconChevronLeftLine />} />
              </AppBar.Left>
              <AppBar.Main layout="withSubtitle">
                <AppBar.Title>화면 제목</AppBar.Title>
                <AppBar.Subtitle>보조 제목</AppBar.Subtitle>
              </AppBar.Main>
              <AppBar.Right>
                <AppBar.IconButton accessibility-label="닫기" icon={<IconXmarkLine />} />
              </AppBar.Right>
            </AppBar.Root>
          </view>
        </view>

        <view className="app-bar-preview__platform">
          <text className="app-bar-preview__label">Android</text>
          <view className="app-bar-preview app-bar-preview--platform">
            <AppBar.Root theme="android">
              <AppBar.Left>
                <AppBar.IconButton accessibility-label="뒤로" icon={<IconChevronLeftLine />} />
              </AppBar.Left>
              <AppBar.Main layout="withSubtitle">
                <AppBar.Title>화면 제목</AppBar.Title>
                <AppBar.Subtitle>보조 제목</AppBar.Subtitle>
              </AppBar.Main>
              <AppBar.Right>
                <AppBar.IconButton accessibility-label="닫기" icon={<IconXmarkLine />} />
              </AppBar.Right>
            </AppBar.Root>
          </view>
        </view>
      </view>
    </page>
  );
}

root.render(<Root />);
```

## Web Version Differences

<Callout type="warning">
  Lynx `AppBar`는 React `AppBar`와 같은 Rootage 기반 variant를 사용하지만, Stackflow와 화면 전환 로직은 포함하지 않습니다.

  - **이벤트 핸들링**: `onClick` 대신 Lynx 이벤트인 `bindtap`을 전달합니다.
  - **렌더링 요소**: HTML 요소 대신 네이티브 `<view>` / `<text>` 요소를 렌더링합니다.
  - **접근성 라벨링**: `aria-label` 대신 Lynx native `accessibility-label`을 사용합니다.
  - **platform theme**: 웹처럼 `data-*` selector에 의존하지 않고, recipe variant className으로 `"cupertino"` / `"android"` 디자인을 적용합니다.
  - **navigation 책임**: `AppBarBackButton`과 `AppBarCloseButton`은 이동을 자동 실행하지 않습니다. Stackflow `pop()` 같은 동작은 호출부에서 연결합니다.
</Callout>

## Unsupported Lynx Features

현재 Lynx AppBar는 순수 UI 컴포넌트로 제공되며 다음 기능은 포함하지 않습니다.

| 기능                          | 웹 대응                                         | 대체 방법                                             |
| --------------------------- | -------------------------------------------- | ------------------------------------------------- |
| Stackflow activity 연동       | `useActivity`, `useActions` 기반 back/close 처리 | `bindtap`에서 앱의 navigation 함수를 직접 호출               |
| swipe-back 전환 애니메이션         | Stackflow screen transition                  | 화면 전환을 소유한 navigation 계층에서 처리                     |
| `data-*` selector 기반 상태 스타일 | 웹 recipe selector                            | `theme`, `tone` variant className 사용              |
| HTML button 속성              | `type`, DOM click event                      | Lynx `<view>` 기반 `AppBarIconButton`과 `bindtap` 사용 |
| HTML ARIA 라벨                | `aria-label`                                 | Lynx native `accessibility-label` 사용              |