@liner-fe/prism 3.4.11 → 3.5.1

package/lib/index.d.ts

@@ -1,13 +1,13 @@
 import { SystemKeys, TypographyCaptionPrefix, TypographyParagraphPrefix, TypographyHeadingPrefix, TypographyTitlePrefix, TypographyDisplayPrefix, BasicColorType } from '@liner-fe/design-token-primitive';
 import * as react from 'react';
-import react__default, { ButtonHTMLAttributes, HTMLAttributes, JSX, ReactNode, ComponentPropsWithoutRef, InputHTMLAttributes, ComponentProps, LiHTMLAttributes, MouseEventHandler, ReactElement } from 'react';
+import react__default, { ButtonHTMLAttributes, HTMLAttributes, JSX, ReactNode, ComponentPropsWithoutRef, InputHTMLAttributes, MouseEventHandler, ReactElement } from 'react';
 import * as cva from 'cva';
 import { VariantProps } from 'cva';
 import { IconProps, IconComponentType } from '@liner-fe/icon';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _artsy_fresnel_dist_Media from '@artsy/fresnel/dist/Media';
 import { breakpointOrigin } from '@liner-fe/design-token';
-import { Popover as Popover$1, Tooltip as Tooltip$1, Checkbox as Checkbox$1, RadioGroup, Select as Select$1, Label as Label$1, AlertDialog as AlertDialog$1, Dialog as Dialog$1 } from 'radix-ui';
+import { Popover as Popover$1, Tooltip as Tooltip$1, Checkbox as Checkbox$1, RadioGroup, Select as Select$1, Label as Label$1, Avatar as Avatar$1, AlertDialog as AlertDialog$1, Dialog as Dialog$1 } from 'radix-ui';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import { PopoverProps, PopoverPortalProps } from '@radix-ui/react-popover';
 import { Drawer } from 'vaul';
@@ -375,48 +375,177 @@ interface TextfieldProps extends InputHTMLAttributes<HTMLInputElement>, VariantP
 }
 declare const Textfield: react.ForwardRefExoticComponent<TextfieldProps & react.RefAttributes<HTMLInputElement>>;
 
-interface SelectProps extends ComponentPropsWithoutRef<typeof Select$1.Root> {
-    id?: string;
-    placeholder?: string;
-    label?: string;
-    chip?: string;
-    listLabel?: string;
-    popSide?: ComponentProps<typeof Select$1.Content>['side'];
-    sideOffset?: ComponentProps<typeof Select$1.Content>['sideOffset'];
-    isResponsive?: boolean;
-    openDirection?: 'slide-up' | 'slide-right';
-    badge?: string;
-    container?: HTMLElement;
+type RadixSelectRootProps = ComponentPropsWithoutRef<typeof Select$1.Root>;
+type SelectTriggerType = 'select-field' | 'select-button';
+type SelectFieldSize = 's' | 'l';
+type SelectButtonSize = 's' | 'm';
+interface SelectWidthOptions {
+    /** Trigger 폭 px override. 미지정 시 Figma 기본 (size별 hardcoded). */
+    trigger?: number;
+    /** Popover list 폭 px override. 미지정 시 default (field=trigger 추종, button=320). */
+    list?: number;
+}
+interface BaseSelectProps extends Omit<RadixSelectRootProps, 'children' | 'dir'> {
+    label?: ReactNode;
+    /**
+     * 아무것도 선택되지 않은 초기 상태에 Trigger에 노출되는 안내 텍스트.
+     * `ReactNode` — 단순 문자열 외 아이콘 + 텍스트 조합 등 가능.
+     * field trigger: Paragraph size=3 tertiary color (Figma 17113:2379).
+     * button trigger: Paragraph size=4 primary color (Figma 17228:64663).
+     */
+    placeholder?: ReactNode;
+    error?: ReactNode;
+    /**
+     * Trigger에 표시할 커스텀 ReactNode (flat prop — 객체 안 nested 금지).
+     *
+     * **객체 prop의 React element가 아닌 flat prop으로 받는 이유**:
+     * Storybook의 react-element-to-jsx-string은 object prop 안의 React element를 parse할 때
+     * 무한 재귀(stack overflow)에 빠짐 → docs 페이지 freeze. flat prop은 정상 처리.
+     *
+     * **사용 책임**:
+     * - controlled `value` + `onValueChange`로 현재 값 알고 렌더
+     * - placeholder 분기도 consumer가 처리 (예: `value ? <Custom/> : undefined`)
+     * - ARIA accessible name 보장
+     *
+     * 미제공 시 기본 RadixSelect.Value 동작: placeholder + ItemText auto-mirror.
+     */
+    triggerContent?: ReactNode;
+    /**
+     * Width override (px). number만 — 자동 px 변환. number는 React element가 아니라
+     * react-element-to-jsx-string 무한재귀 문제 없음 (객체 nested 안전).
+     * 미지정 필드는 Figma 기본 spec:
+     * - `trigger`: trigger × size별 hardcoded (field s=200/l=240, button s=105/m=123)
+     * - `list`: field=trigger 폭 추종, button=320px
+     */
+    width?: SelectWidthOptions;
+    dir?: 'ltr' | 'rtl';
+    children?: ReactNode;
+    className?: string;
+}
+type SelectProps = (BaseSelectProps & {
+    trigger?: 'select-field';
+    size?: SelectFieldSize;
+}) | (BaseSelectProps & {
+    trigger: 'select-button';
+    size?: SelectButtonSize;
+});
+interface SelectContentProps extends ComponentPropsWithoutRef<typeof Select$1.Content> {
+    /**
+     * Popover Portal의 mount 대상 element. 미지정 시 `document.body` (Radix 기본).
+     * 사용 케이스: Radix Dialog/Sheet 내부 mount로 focus trap·z-index 정상화,
+     * scroll container 안 mount, Shadow DOM 등.
+     */
+    container?: HTMLElement | null;
 }
-interface SelectItemProps {
+interface SelectItemProps extends Omit<ComponentPropsWithoutRef<typeof Select$1.Item>, 'value'> {
     value: string;
-    text?: string;
+    label: ReactNode;
+    description?: ReactNode;
+    leadingSlot?: ReactNode;
+    labelEnd?: ReactNode;
+    /**
+     * 우측 영역 (chevron / IconButton / 액션 등). 미제공 + selected 시
+     * 자동으로 brand color IconCheckMark 표시 (Figma `selectItem` 스펙).
+     */
+    trailingSlot?: ReactNode;
+    textValue?: string;
     disabled?: boolean;
-    icon?: {
-        icon: IconComponentType;
-    } & Pick<IconProps, 'fill' | 'type' | 'fillType' | 'size'>;
-    onClick?: () => void;
+    danger?: boolean;
+    /**
+     * 클릭 시 호출. 선택과 함께 navigation 등 link-like 액션을 트리거하려면
+     * 여기서 `router.push(...)` 등을 호출. RadixSelect.Item native onClick passthrough.
+     */
+    onClick?: ComponentPropsWithoutRef<typeof Select$1.Item>['onClick'];
+}
+interface SelectGroupProps extends ComponentPropsWithoutRef<typeof Select$1.Group> {
+    label?: ReactNode;
+}
+interface BaseSelectTriggerProps {
+    label?: ReactNode;
+    placeholder?: ReactNode;
+    error?: ReactNode;
+    /** value 선택 시 표시할 ReactNode. 미제공 시 placeholder 노출. */
+    triggerContent?: ReactNode;
+    /** Trigger 폭 px override (number만). 미지정 시 Figma 기본 spec. */
+    width?: number;
+    required?: boolean;
+    disabled?: boolean;
+    className?: string;
+    onClick?: MouseEventHandler<HTMLButtonElement>;
+    /** Sheet/Dialog context용 ARIA. 기본 미설정 — consumer 책임. */
+    'aria-haspopup'?: 'dialog' | 'listbox' | 'menu' | 'tree' | 'grid';
+    'aria-expanded'?: boolean;
+    'aria-controls'?: string;
+    'aria-label'?: string;
+    id?: string;
 }
+type SelectTriggerProps = (BaseSelectTriggerProps & {
+    trigger?: 'select-field';
+    size?: SelectFieldSize;
+}) | (BaseSelectTriggerProps & {
+    trigger: 'select-button';
+    size?: SelectButtonSize;
+});
 declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>> & {
-    Item: ({ value, text, disabled, icon, onClick }: SelectItemProps) => react_jsx_runtime.JSX.Element;
+    Trigger: react.ForwardRefExoticComponent<SelectTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+    Content: react.ForwardRefExoticComponent<SelectContentProps & react.RefAttributes<HTMLDivElement>>;
+    Item: react.ForwardRefExoticComponent<SelectItemProps & react.RefAttributes<HTMLDivElement>>;
+    Group: react.ForwardRefExoticComponent<SelectGroupProps & react.RefAttributes<HTMLDivElement>>;
 };
 
-interface ListRootProps extends LiHTMLAttributes<HTMLUListElement> {
-    children?: ReactNode;
-    value?: string;
-    onChangeValue?: (value: string) => void;
+type NativeLiProps$1 = Omit<ComponentPropsWithoutRef<'li'>, 'onClick' | 'role'>;
+interface ListItemProps extends NativeLiProps$1 {
+    value: string;
+    label: ReactNode;
+    description?: ReactNode;
+    leadingSlot?: ReactNode;
+    labelEnd?: ReactNode;
+    trailingSlot?: ReactNode;
+    disabled?: boolean;
+    danger?: boolean;
+    onClick?: () => void;
 }
-interface ItemProps {
+/**
+ * @description Figma listItem (17159:3267) 디자인을 입힌 styled ListItem.
+ * 부모 `<CollectionProvider>`(또는 향후 `<List>`)로부터 selected 자동 매칭.
+ * 커스텀 스타일이 필요하면 `PrimitiveListItem`을 직접 wrap.
+ */
+declare const ListItem: react.ForwardRefExoticComponent<ListItemProps & react.RefAttributes<HTMLLIElement>>;
+
+type NativeLiProps = Omit<ComponentPropsWithoutRef<'li'>, 'onClick' | 'role'>;
+interface PrimitiveListItemProps extends NativeLiProps {
     value: string;
-    text: string;
+    leadingSlot?: ReactNode;
+    children: ReactNode;
+    trailingSlot?: ReactNode;
     disabled?: boolean;
-    icon?: {
-        icon: IconComponentType;
-    } & Pick<IconProps, 'fill' | 'type' | 'fillType' | 'size'>;
     onClick?: () => void;
+    role?: 'option' | 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
+}
+/**
+ * @description PrimitiveListItem — 커스텀 스타일용 base.
+ * 기본 사용은 `ListItem`을 권장. `role`은 wrapper(ListItem, SelectItem, ActionMenuItem 등)가 책임 — 외부 직접 지정 금지.
+ * `<CollectionProvider>` 내부에서만 사용 — 외부 사용 시 throw.
+ * `onClick`은 event 인자 없는 `() => void`. event 접근이 필요하면 spread되는 native handler(`onMouseDown` / `onKeyDown` 등) 사용.
+ */
+declare const PrimitiveListItem: react.ForwardRefExoticComponent<PrimitiveListItemProps & react.RefAttributes<HTMLLIElement>>;
+
+type NativeUlProps = Omit<ComponentPropsWithoutRef<'ul'>, 'onChange' | 'role' | 'defaultValue' | 'dir'>;
+interface ListProps extends NativeUlProps {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    loop?: boolean;
+    dir?: 'ltr' | 'rtl';
+    children?: ReactNode;
 }
-declare const List: (({ children, className, ...props }: ListRootProps) => react_jsx_runtime.JSX.Element) & {
-    Item: ({ value, text, disabled, icon, onClick }: ItemProps) => react_jsx_runtime.JSX.Element;
+interface ListGroupProps extends ComponentPropsWithoutRef<'div'> {
+    label?: ReactNode;
+}
+declare const List: react.ForwardRefExoticComponent<ListProps & react.RefAttributes<HTMLUListElement>> & {
+    Item: react.ForwardRefExoticComponent<ListItemProps & react.RefAttributes<HTMLLIElement>>;
+    PrimitiveItem: react.ForwardRefExoticComponent<PrimitiveListItemProps & react.RefAttributes<HTMLLIElement>>;
+    Group: react.ForwardRefExoticComponent<ListGroupProps & react.RefAttributes<HTMLDivElement>>;
 };
 
 declare const defaultLabelVariants: (props?: ({
@@ -642,6 +771,47 @@ type BadgeBaseProps = ComponentPropsWithoutRef<'span'> & {
 type BadgeProps = BadgeBaseProps & BadgeVariantColorProps;
 declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttributes<HTMLSpanElement>>;
 
+type AvatarSize = 'small' | 'medium' | 'xlarge';
+/**
+ * 이미지 로딩 상태(`'idle' | 'loading' | 'loaded' | 'error'`).
+ * union 을 직접 정의하지 않고 radix-ui Avatar.Image 의 타입을 그대로 파생해 재사용합니다(drift 방지).
+ */
+type AvatarLoadingStatus = Parameters<NonNullable<ComponentPropsWithoutRef<typeof Avatar$1.Image>['onLoadingStatusChange']>>[0];
+type AvatarProps = ComponentPropsWithoutRef<typeof Avatar$1.Root> & {
+    /** 아바타 크기. */
+    size?: AvatarSize;
+    /**
+     * 사용자 이미지 URL. prop 전달은 필수이지만 값으로 `undefined` 를 허용합니다(`src?:` 옵셔널 아님).
+     * 호출부가 src 를 깜빡 누락하는 것은 막되, 사진이 없으면 `undefined` 를 명시적으로 넘길 수 있습니다.
+     * `undefined`/빈 문자열이거나 로드에 실패하면 fallback 이미지를 표시합니다.
+     */
+    src: string | undefined;
+    /** 이미지 대체 텍스트(접근성). 사용자 이름 등을 전달합니다. 장식용이면 빈 문자열(`''`)을 넘기세요. */
+    alt: string;
+    /** 이미지 로딩 상태가 바뀔 때 호출됩니다. (idle → loading → loaded | error) */
+    onLoadingStatusChange?: (status: AvatarLoadingStatus) => void;
+};
+/**
+ * 사용자/엔티티를 원형 이미지로 표현하는 Avatar.
+ *
+ * radix-ui Avatar 를 래핑합니다. `src` 이미지가 로드되기 전·로드에 실패했을 때(빈 URL 포함)는
+ * fallback placeholder 이미지를 보여줍니다. 로딩 중 깨진 이미지가 잠깐 보이는 현상이 없습니다.
+ */
+declare const Avatar: react.ForwardRefExoticComponent<Omit<Avatar$1.AvatarProps & react.RefAttributes<HTMLSpanElement>, "ref"> & {
+    /** 아바타 크기. */
+    size?: AvatarSize;
+    /**
+     * 사용자 이미지 URL. prop 전달은 필수이지만 값으로 `undefined` 를 허용합니다(`src?:` 옵셔널 아님).
+     * 호출부가 src 를 깜빡 누락하는 것은 막되, 사진이 없으면 `undefined` 를 명시적으로 넘길 수 있습니다.
+     * `undefined`/빈 문자열이거나 로드에 실패하면 fallback 이미지를 표시합니다.
+     */
+    src: string | undefined;
+    /** 이미지 대체 텍스트(접근성). 사용자 이름 등을 전달합니다. 장식용이면 빈 문자열(`''`)을 넘기세요. */
+    alt: string;
+    /** 이미지 로딩 상태가 바뀔 때 호출됩니다. (idle → loading → loaded | error) */
+    onLoadingStatusChange?: (status: AvatarLoadingStatus) => void;
+} & react.RefAttributes<HTMLSpanElement>>;
+
 /**
  * AlertDialogRoot
  *
@@ -841,4 +1011,4 @@ interface RatioProps extends react.HTMLAttributes<HTMLDivElement> {
  */
 declare const Ratio: react.ForwardRefExoticComponent<RatioProps & react.RefAttributes<HTMLDivElement>>;
 
-export { AlertDialog, type AlertDialogAction, type AlertDialogConfirmAction, type AlertDialogContentProps, Badge, type BadgeColor, type BadgeIconProps, type BadgeProps, type BadgeSize, type BadgeVariant, BottomSheet, type BottomSheetAction, type BottomSheetConfirmAction, type BottomSheetContentProps, type BottomSheetMode, type BreakPointsKey, Button, type ButtonIconProps, type ButtonProps, type ButtonSizeType, Caption, Checkbox, CoachMark, type CoachMarkContentProps, type CommonButtonProps, CompactCoachMark, type CompactCoachMarkContentProps, DEFAULT_LEVEL_OPTIONS, DEFAULT_SIZE_OPTIONS, DefaultButton, type DefaultButtonProps, type DefaultLevelType, Dialog, type DialogAction, type DialogConfirmAction, type DialogContentProps, Display, Heading, ICON_LEVEL_OPTIONS, ICON_SIZE_OPTIONS, type ICaptionProps, type IDisplayProps, type IHeadingProps, type IPropsAccent, type IPropsAnswer, type IPropsNormal, type IPropsNormalBold, type IPropsPost, type ITitleProps, IconButton, type IconButtonProps, type ItemProps, LOGOS, Label, List, Loading, type LoadingLevelType, Logo, type LogoCategory, type LogoName, type LogoProps, Media, MediaContextProvider, Paragraph, type ParagraphProps, Popover, type PopoverContentProps, PrimitiveCoachMark, type PrimitiveCoachMarkContentProps, type PrimitiveCoachMarkRootProps, type PromiseToastOptions, RATIO, Radio, Ratio, type RatioProps, Select, type SelectItemProps, type SelectProps, TEXT_LEVEL_OPTIONS, TEXT_SIZE_OPTIONS, Tag, TextButton, type TextButtonProps, type TextSizeType, Textfield, type TextfieldButtonProps, type TextfieldLabelType, type TextfieldProps, Title, type ToastOptions, type ToastType, Toaster, Tooltip, Typography, arrayToStyleObject, isEmptyObject, objectToArray, rootMediaStyle, toast };
+export { AlertDialog, type AlertDialogAction, type AlertDialogConfirmAction, type AlertDialogContentProps, Avatar, type AvatarLoadingStatus, type AvatarProps, type AvatarSize, Badge, type BadgeColor, type BadgeIconProps, type BadgeProps, type BadgeSize, type BadgeVariant, BottomSheet, type BottomSheetAction, type BottomSheetConfirmAction, type BottomSheetContentProps, type BottomSheetMode, type BreakPointsKey, Button, type ButtonIconProps, type ButtonProps, type ButtonSizeType, Caption, Checkbox, CoachMark, type CoachMarkContentProps, type CommonButtonProps, CompactCoachMark, type CompactCoachMarkContentProps, DEFAULT_LEVEL_OPTIONS, DEFAULT_SIZE_OPTIONS, DefaultButton, type DefaultButtonProps, type DefaultLevelType, Dialog, type DialogAction, type DialogConfirmAction, type DialogContentProps, Display, Heading, ICON_LEVEL_OPTIONS, ICON_SIZE_OPTIONS, type ICaptionProps, type IDisplayProps, type IHeadingProps, type IPropsAccent, type IPropsAnswer, type IPropsNormal, type IPropsNormalBold, type IPropsPost, type ITitleProps, IconButton, type IconButtonProps, LOGOS, Label, List, type ListGroupProps, ListItem, type ListItemProps, type ListProps, Loading, type LoadingLevelType, Logo, type LogoCategory, type LogoName, type LogoProps, Media, MediaContextProvider, Paragraph, type ParagraphProps, Popover, type PopoverContentProps, PrimitiveCoachMark, type PrimitiveCoachMarkContentProps, type PrimitiveCoachMarkRootProps, PrimitiveListItem, type PrimitiveListItemProps, type PromiseToastOptions, RATIO, Radio, Ratio, type RatioProps, Select, type SelectButtonSize, type SelectContentProps, type SelectFieldSize, type SelectGroupProps, type SelectItemProps, type SelectProps, type SelectTriggerProps, type SelectTriggerType, type SelectWidthOptions, TEXT_LEVEL_OPTIONS, TEXT_SIZE_OPTIONS, Tag, TextButton, type TextButtonProps, type TextSizeType, Textfield, type TextfieldButtonProps, type TextfieldLabelType, type TextfieldProps, Title, type ToastOptions, type ToastType, Toaster, Tooltip, Typography, arrayToStyleObject, isEmptyObject, objectToArray, rootMediaStyle, toast };