# Quantity Picker
URL: /lynx/components/quantity-picker
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/quantity-picker.mdx

정수 단위의 수량을 늘리거나 줄일 때 사용하는 컴포넌트입니다.

Lynx Engine 최소 버전: 3.6

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

## Preview

```tsx
import "./styles";

import { QuantityPicker } from "@/components/ui/quantity-picker";

export default function Example() {
  return <QuantityPicker min={1} max={99} defaultValue={1} accessibility-label="상품 수량" />;
}
```

## Installation

- npm: npx @seed-design/cli@latest add ui:quantity-picker
- pnpm: pnpm dlx @seed-design/cli@latest add ui:quantity-picker
- yarn: yarn dlx @seed-design/cli@latest add ui:quantity-picker
- bun: bun x @seed-design/cli@latest add ui:quantity-picker

## Props

### `QuantityPicker`

Registry의 `QuantityPicker`는 수량 선택에 필요한 감소 버튼, 값, 증가 버튼을 함께 제공합니다.

`min`과 `max`는 필수이며 안전한 정수여야 합니다. `step`의 기본값은 `1`이고, `defaultValue`를 생략하면 `min`에서 시작합니다. `value`와 `onValueChange`를 함께 사용하면 값을 외부 상태로 제어할 수 있습니다.

## Examples

### Layout

`layout="hug"`는 콘텐츠에 맞는 너비를 유지합니다. 부모가 Flex 레이아웃이고 남은 공간을 채워야 한다면 `layout="fill"`을 사용하세요. 양쪽 버튼 크기는 유지되고 Value Display 영역만 늘어납니다.

```tsx
import "./styles";

import { QuantityPicker } from "@/components/ui/quantity-picker";

export default function Example() {
  return (
    <view className="quantity-picker-example quantity-picker-layout-host">
      <text className="quantity-picker-example-title">Layout</text>
      <view className="quantity-picker-layout-row">
        <text className="quantity-picker-layout-label">Hug (기본)</text>
        <view className="quantity-picker-example-controls">
          <QuantityPicker
            layout="hug"
            min={1}
            max={99}
            defaultValue={1}
            accessibility-label="Hug 상품 수량"
          />
        </view>
      </view>
      <view className="quantity-picker-layout-row">
        <text className="quantity-picker-layout-label">Fill</text>
        <view className="quantity-picker-example-controls">
          <QuantityPicker
            layout="fill"
            min={1}
            max={99}
            defaultValue={1}
            accessibility-label="Fill 상품 수량"
          />
        </view>
      </view>
    </view>
  );
}
```

이 예제에서 사용하는 Quantity Picker recipe는 `display: grid`를 사용합니다. Android/iOS Lynx engine 2.1 이상과 HarmonyOS Lynx engine 3.4 이상에서 호환됩니다.

### Value Text

`getValueText`를 사용하면 표시되는 수량에 단위나 보조 설명을 덧붙일 수 있습니다. 반환한 값은 Value Display와 접근성 값에 사용할 표시 텍스트이며, 내부 수량 상태나 증감 단위에는 영향을 주지 않습니다.

```tsx
import "./styles";

import { QuantityPicker } from "@/components/ui/quantity-picker";

export default function Example() {
  return (
    <view className="quantity-picker-example">
      <text className="quantity-picker-example-title">Value text</text>
      <view className="quantity-picker-example-controls">
        <QuantityPicker
          min={1}
          max={99}
          defaultValue={1}
          accessibility-label="상품 수량"
          getValueText={(valueText: string) => `${valueText}개`}
        />
      </view>
    </view>
  );
}
```

### Controlled

`value`와 `onValueChange`를 사용해 수량 상태를 앱의 상태로 제어할 수 있습니다. 변경 콜백에서 새 숫자를 저장하고, 저장한 값을 다시 `value`로 전달하세요.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";

import { QuantityPicker } from "@/components/ui/quantity-picker";

export default function Example() {
  const [quantity, setQuantity] = useState(2);

  function handleValueChange(nextQuantity: number) {
    "background only";
    setQuantity(nextQuantity);
  }

  return (
    <view className="quantity-picker-example">
      <text className="quantity-picker-example-title">Controlled</text>
      <QuantityPicker
        min={1}
        max={99}
        value={quantity}
        onValueChange={handleValueChange}
        accessibility-label="상품 수량"
      />
      <text className="quantity-picker-example-status">현재 수량: {quantity}개</text>
    </view>
  );
}
```

### Removable

`removable`을 사용하면 값이 `min`에 도달했을 때 Decrement 버튼이 Remove 버튼으로 전환됩니다. 이때 Decrement를 누르면 수량을 변경하지 않고 `onRemove`만 호출합니다. 삭제나 목록에서 제거하는 동작은 `onRemove`에서 처리하세요.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { ActionButton, VStack } from "@seed-design/lynx-react";
import { QuantityPicker } from "@/components/ui/quantity-picker";

export default function Example() {
  const [removed, setRemoved] = useState(false);

  function handleRemove() {
    "background only";
    setRemoved(true);
  }

  function handleRestore() {
    "background only";
    setRemoved(false);
  }

  return (
    <view className="quantity-picker-example">
      <text className="quantity-picker-example-title">Removable</text>
      {removed ? (
        <VStack gap="x4" align="center">
          <text className="quantity-picker-example-status">상품을 삭제했습니다.</text>
          <view className="quantity-picker-example-controls">
            <ActionButton
              className="quantity-picker-example-control"
              variant="neutralWeak"
              bindtap={handleRestore}
            >
              되돌리기
            </ActionButton>
          </view>
        </VStack>
      ) : (
        <>
          <view className="quantity-picker-example-controls">
            <QuantityPicker
              min={1}
              max={99}
              defaultValue={1}
              removable
              removeAccessibilityLabel="상품 삭제"
              accessibility-label="상품 수량"
              onRemove={handleRemove}
            />
          </view>
          <text className="quantity-picker-example-status">
            최솟값에서 감소 버튼을 누르면 수량 선택기가 제거됩니다.
          </text>
        </>
      )}
    </view>
  );
}
```

### Loading

`loading`으로 모든 action 또는 특정 action의 실행을 일시적으로 막고 loading indicator를 표시할 수 있습니다. `loading={true}`는 Decrement와 Increment 모두에 적용되며, `loading={{ increment: true }}`처럼 객체를 전달하면 해당 action만 막습니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { ActionButton } from "@seed-design/lynx-react";
import { QuantityPicker } from "@/components/ui/quantity-picker";

export default function Example() {
  const [decrementLoading, setDecrementLoading] = useState(false);
  const [incrementLoading, setIncrementLoading] = useState(false);
  const allLoading = decrementLoading && incrementLoading;

  function toggleAllLoading() {
    "background only";
    const nextLoading = !allLoading;
    setDecrementLoading(nextLoading);
    setIncrementLoading(nextLoading);
  }

  function toggleDecrementLoading() {
    "background only";
    setDecrementLoading((current) => !current);
  }

  function toggleIncrementLoading() {
    "background only";
    setIncrementLoading((current) => !current);
  }

  return (
    <view className="quantity-picker-example">
      <text className="quantity-picker-example-title">Loading</text>
      <QuantityPicker
        min={1}
        max={99}
        defaultValue={2}
        loading={
          allLoading
            ? true
            : {
                decrement: decrementLoading,
                increment: incrementLoading,
              }
        }
        accessibility-label="상품 수량"
      />
      <view className="quantity-picker-example-controls">
        <ActionButton
          className="quantity-picker-example-control"
          variant="neutralWeak"
          bindtap={toggleAllLoading}
        >
          전체 {allLoading ? "끄기" : "켜기"}
        </ActionButton>
        <ActionButton
          className="quantity-picker-example-control"
          variant="neutralWeak"
          bindtap={toggleDecrementLoading}
        >
          감소 {decrementLoading ? "끄기" : "켜기"}
        </ActionButton>
        <ActionButton
          className="quantity-picker-example-control"
          variant="neutralWeak"
          bindtap={toggleIncrementLoading}
        >
          증가 {incrementLoading ? "끄기" : "켜기"}
        </ActionButton>
      </view>
      <text className="quantity-picker-example-status">
        감소: {decrementLoading ? "loading" : "준비"} · 증가:{" "}
        {incrementLoading ? "loading" : "준비"}
      </text>
    </view>
  );
}
```

`disabled`, `readOnly`, `loading`은 모두 action을 실행하지 못하게 합니다. `disabled`는 두 action을 비활성화하고 접근성 상태에도 disabled를 전달합니다. `readOnly`는 수량 변경과 Remove 콜백 호출을 막지만 값을 다른 상태로 바꾸지는 않습니다. `loading`은 지정된 action만 일시적으로 막으며, 해당 action의 indicator를 표시합니다. 따라서 `removable`의 최솟값에서도 Decrement가 disabled, readOnly 또는 decrement loading이면 `onRemove`가 호출되지 않습니다.

### Form

Lynx에는 HTML `<form>`, hidden `<input>`, `FormData` 제출 모델이 없으므로 웹의 `inputProps`와 hidden input 기반 Form 예제를 제공하지 않습니다. 수량을 제출해야 할 때는 `value`와 `onValueChange`로 앱 상태를 관리한 뒤, 제출 또는 네트워크 요청을 만드는 코드에서 그 상태를 payload에 직접 넣으세요. 이 방식은 UI 표시용 `getValueText`와 서버에 보낼 raw 숫자 값을 분리할 수 있습니다.

## Accessibility

Quantity Picker의 용도를 설명하는 `accessibility-label`을 제공하세요. 이 label은 현재 수량을 표시하는 요소의 이름으로 사용되며, `getValueText`가 반환한 문자열이나 숫자는 접근성 값에도 반영됩니다.

Registry 컴포넌트는 감소, 증가, 삭제 버튼에 기본 접근성 label을 제공합니다. 문맥에 맞게 바꾸려면 `decrementAccessibilityLabel`, `incrementAccessibilityLabel`, `removeAccessibilityLabel`을 사용하세요. 특히 `removable`을 사용할 때는 삭제 대상을 알 수 있는 label을 제공해야 합니다.

`disabled`는 접근성 상태에도 반영됩니다. `readOnly`와 `loading`으로 동작을 막았다면 주변 label이나 안내 텍스트로 제한 상태를 설명하세요.

## 웹 버전과의 차이

- HTML 요소와 버튼 대신 Lynx native `<view>`와 접근성 요소를 렌더링하고 tap으로 동작합니다.
- `aria-*` 대신 `accessibility-*`와 Registry의 접근성 label props를 사용합니다.
- HTML form, hidden input, `FormData`, `inputProps`를 지원하지 않습니다. 제출할 수량은 `value`와 `onValueChange`로 관리해 요청 payload에 직접 넣으세요.
- 브라우저의 form 검증과 키보드 focus 모델이 없습니다. required 검증과 제출은 앱에서 처리합니다.