sellmate-design-system-react 9.0.0-beta.30 → 9.0.0-beta.32

package/dist/components/SSystemActionButton/SSystemActionButton.d.ts

@@ -1,4 +1,5 @@
 import { type ButtonHTMLAttributes } from 'react';
+import { type SAccountListBoxContent } from '../SAccountListBox';
 import { type SIconName } from '../SIcon';
 import { type STagColor } from '../STag';
 import { type SSystemActionButtonColor } from './systemActionButton.config';
@@ -12,12 +13,49 @@ export interface SSystemActionButtonTextOption extends SSystemActionButtonIconOp
     /** 우측 액션 텍스트 */
     text?: string;
 }
-/** `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 */
-export interface SSystemActionButtonStatusOption {
-    /** 상태 태그 색 */
+/** 값 고르기 메뉴의 한 칸 */
+export interface SSystemActionButtonMenuOption {
+    /** 값. `option.value` 와 맞춰 지금 값을 가린다 */
+    value: string;
+    /** 화면에 적히는 이름 */
+    label: string;
+}
+/**
+ * `subSelect` 타입의 option — 지금 값 + 고를 목록.
+ *
+ * `options` 는 **필수다** — `subSelect` 는 "지금 값이 적혀 있고 눌러서 바꾸는 행"이라, 눌러도
+ * 아무것도 뜨지 않으면 그것은 `select`(눌러 들어가는 행)이지 `subSelect` 가 아니다.
+ */
+export interface SSystemActionButtonSubSelectOption extends SSystemActionButtonIconOption {
+    /**
+     * 지금 값. `options` 에서 같은 `value` 를 찾아 우측에 그 `label` 로 적는다
+     * (못 찾으면 `value` 가 그대로 남는다).
+     */
+    value?: string;
+    /** 고를 수 있는 값. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+    options: SSystemActionButtonMenuOption[];
+    /** 메뉴에서 값을 고름. 고르면 메뉴가 닫힌다 */
+    onChange?: (value: string) => void;
+}
+/** 상태 메뉴의 한 칸 — 점과 글자가 그 상태의 색으로 함께 물든다 */
+export interface SSystemActionButtonStatusMenuOption extends SSystemActionButtonMenuOption {
+    /** 상태 색. 기본 `'blue'` */
     color?: STagColor;
-    /** 상태 태그 텍스트 */
-    label?: string;
+}
+/**
+ * `status` 타입의 option — 라벨 자리에 들어가는 상태 태그 + 고를 목록.
+ *
+ * `options` 는 **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거이고, 지금 상태(`value`)에
+ * 해당하는 칸의 색·이름이 곧 태그가 된다. 보여주기만 하는 상태 줄이 필요하면 이 버튼이 아니라
+ * `STag` 를 쓴다.
+ */
+export interface SSystemActionButtonStatusOption {
+    /** 지금 상태. `options` 에서 같은 `value` 를 찾아 그 색·이름으로 태그를 그린다 */
+    value?: string;
+    /** 고를 수 있는 상태. **필수다** — 이 목록이 행 오른쪽으로 펼쳐진다 */
+    options: SSystemActionButtonStatusMenuOption[];
+    /** 메뉴에서 상태를 고름. 고르면 메뉴가 닫힌다 */
+    onChange?: (value: string) => void;
 }
 /** 모든 타입이 공통으로 받는 props */
 export interface SSystemActionButtonBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'type' | 'children'> {
@@ -26,14 +64,35 @@ export interface SSystemActionButtonBaseProps extends Omit<ButtonHTMLAttributes<
     /** 비활성 여부. 기본 `false` */
     disabled?: boolean;
 }
+/**
+ * `account` 타입의 option — 행을 눌렀을 때 뜨는 계정 리스트박스.
+ * 내용(이메일·이름·권한·행들)은 `SAccountListBox` 와 같다.
+ *
+ * **뜨는 자리는 받지 않는다.** 계정 행이 놓인 자리가 정한다 — 판이면 행 위로 · 왼쪽 끝에 맞춰,
+ * 전폭 상단바면 행 아래로 · 오른쪽 끝에 맞춰 펼친다(시안). 화면마다 고를 값이 아니라,
+ * prop 으로 열면 같은 계정 행이 앱마다 다른 방향으로 뜬다.
+ */
+export interface SSystemActionButtonAccountOption extends SAccountListBoxContent {
+    /**
+     * 리스트박스 열림 상태를 밖에서 쥔다(controlled). 주지 않으면 버튼이 스스로 여닫는다.
+     * 행을 담은 쪽이 닫아야 하는 자리가 있어 열어 둔 통로다 — 리스트박스는 SPortal 로 떠 있어
+     * 트리거가 화면에서 빠져도(GNB 를 접으면 메뉴 컬럼이 미끄러져 나간다) 따라 사라지지 않는다.
+     */
+    open?: boolean;
+    /** 리스트박스 열림/닫힘 변경 */
+    onOpenChange?: (open: boolean) => void;
+}
 /** 계정 행 — 아이콘이 `user` 로 고정이고 우측 액션이 없다 */
 export interface SSystemActionButtonAccountProps extends SSystemActionButtonBaseProps {
     /** 계정 행 */
     type: 'account';
     /** 라벨 텍스트 */
     label?: string;
-    /** 아이콘이 `user` 로 고정이라 받을 것이 없다 */
-    option?: never;
+    /**
+     * 누르면 뜨는 계정 리스트박스. **필수다** — 계정 행은 늘 이 패널의 트리거이고, 눌러도 아무것도
+     * 뜨지 않는 계정 행은 없다. 아이콘은 `user` 로 고정이라 여기서 받지 않는다.
+     */
+    option: SSystemActionButtonAccountOption;
 }
 /** 화살표만 붙는 행 — 눌러 들어간다는 뜻 */
 export interface SSystemActionButtonSelectProps extends SSystemActionButtonBaseProps {
@@ -44,26 +103,39 @@ export interface SSystemActionButtonSelectProps extends SSystemActionButtonBaseP
     /** 선행 아이콘 */
     option: SSystemActionButtonIconOption;
 }
-/** 우측에 문구가 붙는 행 — `switch` 는 보조 조작 문구, `subSelect` 는 지금 선택된 값 */
-export interface SSystemActionButtonTextProps extends SSystemActionButtonBaseProps {
-    /** 우측에 문구가 붙는 행. switch = 보조 조작 문구, subSelect = 지금 선택된 값 */
-    type: 'switch' | 'subSelect';
+/** 우측에 보조 조작 문구가 붙는 행 — 지금 붙어 있는 대상을 갈아 끼운다 */
+export interface SSystemActionButtonSwitchProps extends SSystemActionButtonBaseProps {
+    /** 우측에 보조 조작 문구가 붙는 행 */
+    type: 'switch';
     /** 라벨 텍스트 */
     label?: string;
     /** 선행 아이콘 + 우측 액션 텍스트 */
     option: SSystemActionButtonTextOption;
 }
-/** 라벨 자리에 상태 태그가 들어가는 행 */
+/** 우측에 지금 선택된 값이 붙는 행 — `options` 를 주면 행 오른쪽으로 메뉴가 펼쳐진다 */
+export interface SSystemActionButtonSubSelectProps extends SSystemActionButtonBaseProps {
+    /** 우측에 지금 선택된 값이 붙는 행 */
+    type: 'subSelect';
+    /** 라벨 텍스트 */
+    label?: string;
+    /** 선행 아이콘 + 우측 값 + 고를 목록 */
+    option: SSystemActionButtonSubSelectOption;
+}
+/** 우측에 문구가 붙는 두 타입을 함께 가리킨다 — `switch` · `subSelect` */
+export type SSystemActionButtonTextProps = SSystemActionButtonSwitchProps | SSystemActionButtonSubSelectProps;
+/** 라벨 자리에 상태 태그가 들어가는 행 — `options` 를 주면 행 오른쪽으로 메뉴가 펼쳐진다 */
 export interface SSystemActionButtonStatusProps extends SSystemActionButtonBaseProps {
     /** 라벨 자리에 상태 태그가 들어가는 행 */
     type: 'status';
     /** 태그가 라벨 자리를 차지하므로 받지 않는다 */
     label?: never;
-    /** 상태 태그 */
-    option?: SSystemActionButtonStatusOption;
+    /**
+     * 상태 태그 + 고를 목록. **필수다** — 상태 행은 늘 그 상태를 바꾸는 메뉴의 트리거다.
+     */
+    option: SSystemActionButtonStatusOption;
 }
 /** `type` 으로 갈리는 판별 유니온. 타입에 맞지 않는 option 은 컴파일 단계에서 막힌다. */
-export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystemActionButtonSelectProps | SSystemActionButtonTextProps | SSystemActionButtonStatusProps;
+export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystemActionButtonSelectProps | SSystemActionButtonSwitchProps | SSystemActionButtonSubSelectProps | SSystemActionButtonStatusProps;
 /**
  * SSystemActionButton — GNB system 패널의 한 줄짜리 액션 버튼.
  *
@@ -72,6 +144,16 @@ export type SSystemActionButtonProps = SSystemActionButtonAccountProps | SSystem
  * `option` 으로 받는다. 선행 아이콘은 항상 있다 — `account` 는 `user` 고정, `status` 는 태그가
  * 자리를 차지해 아이콘이 없고, 나머지는 `option.icon` 이 필수다.
  *
+ * `account` 는 **언제나 계정 리스트박스(`SAccountListBox`)의 트리거**다 — 눌러도 아무것도 뜨지
+ * 않는 계정 행은 없으므로 `option` 이 필수이고, 누르면 이메일·이름·권한과 계정 설정·언어 변경·
+ * 로그아웃을 보여주고 행을 고르면 닫힌다. 뜨는 자리는 받지 않고 놓인 자리가 정한다
+ * (판이면 행 위로 · 왼쪽 끝, 전폭 상단바면 행 아래로 · 오른쪽 끝).
+ *
+ * `subSelect` · `status` 는 **언제나 값 고르기 메뉴의 트리거**다 — 지금 값이 적혀 있는 행이라
+ * 누르면 그 값을 바꾸는 메뉴가 뜬다. 그래서 `option.options` 가 필수이고, 메뉴는 행 오른쪽으로
+ * (행 위쪽 끝에 맞춰) 펼쳐지며 고르면 `option.onChange(value)` 가 돌고 닫힌다.
+ * 눌러서 값 고르는 화면으로 보낼 것이면 `select`, 보여주기만 할 것이면 `STag` 다.
+ *
  * hover 하면 표면색이 한 단계 바뀌고, 어두운 색에서는 아이콘 프레임이 흰색으로 떠오른다.
  * 상태는 default·hover 둘뿐이다 — 토큰에 selected 가 없다.
  * 토큰은 `--cmp-gnb-system-item-*` · `--cmp-gnb-system-actionButton-*`.

package/dist/components/SSystemActionButton/index.d.ts

@@ -1,2 +1,2 @@
-export { SSystemActionButton, type SSystemActionButtonProps, type SSystemActionButtonBaseProps, type SSystemActionButtonAccountProps, type SSystemActionButtonSelectProps, type SSystemActionButtonTextProps, type SSystemActionButtonStatusProps, type SSystemActionButtonIconOption, type SSystemActionButtonTextOption, type SSystemActionButtonStatusOption, } from './SSystemActionButton';
+export { SSystemActionButton, type SSystemActionButtonProps, type SSystemActionButtonBaseProps, type SSystemActionButtonAccountProps, type SSystemActionButtonAccountOption, type SSystemActionButtonSelectProps, type SSystemActionButtonTextProps, type SSystemActionButtonSwitchProps, type SSystemActionButtonSubSelectProps, type SSystemActionButtonStatusProps, type SSystemActionButtonIconOption, type SSystemActionButtonTextOption, type SSystemActionButtonSubSelectOption, type SSystemActionButtonMenuOption, type SSystemActionButtonStatusOption, type SSystemActionButtonStatusMenuOption, } from './SSystemActionButton';
 export { SYSTEM_ACTION_BUTTON_COLORS, SYSTEM_ACTION_BUTTON_TYPES, SYSTEM_ACTION_BUTTON_COLOR_CONFIG, SYSTEM_ACTION_BUTTON_TYPE_CONFIG, SYSTEM_ACTION_BUTTON_LAYOUT, type SSystemActionButtonColor, type SSystemActionButtonType, } from './systemActionButton.config';