@ceed/cds 1.24.1-next.3 → 1.26.0

package/dist/chunks/rehype-accent-FZRUD7VI.js

@@ -0,0 +1,39 @@
+// src/libs/rehype-accent/index.ts
+import { visit } from "unist-util-visit";
+function rehypeAccent(options) {
+  const { accentColor } = options;
+  return (tree) => {
+    visit(tree, "text", (node, index, parent) => {
+      const value = node.value;
+      const regex = /\|\|.*?\|\|/g;
+      let match;
+      let lastIndex = 0;
+      const newNodes = [];
+      while ((match = regex.exec(value)) !== null) {
+        if (match.index > lastIndex) {
+          newNodes.push({
+            type: "text",
+            value: value.slice(lastIndex, match.index)
+          });
+        }
+        const innerText = match[0].split("||")[1];
+        newNodes.push({
+          type: "element",
+          tagName: "span",
+          properties: { textColor: accentColor },
+          children: [{ type: "text", value: innerText }]
+        });
+        lastIndex = match.index + match[0].length;
+      }
+      if (lastIndex < value.length) {
+        newNodes.push({ type: "text", value: value.slice(lastIndex) });
+      }
+      if (newNodes.length) {
+        parent.children.splice(index, 1, ...newNodes);
+      }
+    });
+  };
+}
+export {
+  rehypeAccent
+};

package/dist/components/CurrencyInput/CurrencyInput.d.ts

@@ -2,7 +2,7 @@ import React from 'react';
 import { InputProps } from '@mui/joy';
 import { MotionProps } from 'framer-motion';
 interface CurrencyInputProps {
-    currency?: 'USD' | 'KRW';
+    currency?: 'USD' | 'KRW' | 'CAD';
     max?: number;
     value?: number;
     defaultValue?: number;

package/dist/components/CurrencyInput/hooks/use-currency-setting.d.ts

@@ -1,10 +1,10 @@
 export declare const useCurrencySetting: (props: {
-    currency?: "USD" | "KRW" | "BHD" | undefined;
+    currency?: "USD" | "KRW" | "BHD" | "CAD" | undefined;
     placeholder?: string | undefined;
 }) => {
     symbol: string;
     thousandSeparator: string;
-    decimalSeparator: string;
+    decimalSeparator: string | undefined;
     placeholder: string;
     fixedDecimalScale: boolean;
     decimalScale: number;

package/dist/components/DataTable/components.d.ts

@@ -1,7 +1,8 @@
 import React, { ReactNode } from 'react';
 import type { ObjectLike, ColumnDef, Sort } from './types';
-export declare const TextEllipsis: ({ children }: {
+export declare const TextEllipsis: ({ children, lineClamp }: {
     children: ReactNode;
+    lineClamp?: number | undefined;
 }) => React.JSX.Element;
 export declare const CellTextEllipsis: ({ children }: {
     children: ReactNode;

package/dist/components/DataTable/hooks.d.ts

@@ -5,7 +5,7 @@ export declare function useColumnWidths<T>(columnsByField: {
         headerRef: React.RefObject<HTMLTableCellElement>;
     };
 }): Record<string, number>;
-export declare function useDataTableRenderer<T extends Record<PropertyKey, unknown>, GetId extends ((row: T) => any) | undefined = undefined>({ rows: _rows, columns: columnsProp, pinnedColumns, rowCount: totalRowsProp, initialState, pagination, paginationMode, paginationModel, onPaginationModelChange, sortModel: controlledSortModel, sortOrder: _sortOrder, selectionModel, onSortModelChange, onSelectionModelChange, editMode, getId: _getId, isTotalSelected: _isTotalSelected, isRowSelectable, columnGroupingModel, }: DataTableProps<T, GetId>): {
+export declare function useDataTableRenderer<T extends Record<PropertyKey, unknown>, GetId extends ((row: T) => any) | undefined = undefined>({ rows: _rows, columns: columnsProp, pinnedColumns, rowCount: totalRowsProp, initialState, pagination, paginationMode, paginationModel, onPaginationModelChange, sortModel: controlledSortModel, sortOrder: _sortOrder, selectionModel, onSortModelChange, onSelectionModelChange, editMode, getId: _getId, isTotalSelected: _isTotalSelected, isRowSelectable, columnGroupingModel, columnVisibilityModel, onColumnVisibilityModelChange, }: DataTableProps<T, GetId>): {
     rowCount: number;
     selectableRowCount: number;
     page: number;

package/dist/components/DataTable/styled.d.ts

@@ -1,5 +1,7 @@
 import React, { RefObject } from 'react';
-export declare const EllipsisDiv: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof React.ClassAttributes<HTMLDivElement> | keyof React.HTMLAttributes<HTMLDivElement>>, {}>;
+export declare const EllipsisDiv: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme> & {
+    lineClamp?: number | undefined;
+}, React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const OverlayWrapper: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLTableRowElement>, HTMLTableRowElement>, keyof React.ClassAttributes<HTMLTableRowElement> | keyof React.HTMLAttributes<HTMLTableRowElement>>, {}>;
 export declare const VirtualizedTableBody: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme>, Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLTableSectionElement>, HTMLTableSectionElement>, keyof React.ClassAttributes<HTMLTableSectionElement> | keyof React.HTMLAttributes<HTMLTableSectionElement>>, {}>;
 export declare const StyledTableRow: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<import("@mui/joy").Theme> & {

package/dist/components/DataTable/types.d.ts

@@ -103,6 +103,7 @@ export type BaseColumnDef<T extends Record<PropertyKey, V>, V, ID> = {
         description?: string;
         cellClassName?: TableCellClassNamePropType<T, T[K]>;
         headerClassName?: TableColumnHeaderClassNamePropType<T, T[K]>;
+        headerLineClamp?: 1 | 2;
     };
 }[keyof T];
 export type AutocompleteColumnDef<T extends Record<PropertyKey, string>, ID> = BaseColumnDef<T, string, ID> & {
@@ -147,6 +148,7 @@ export type ActionsColumnDef<T extends Record<PropertyKey, string>, ID> = BaseCo
     }) => ReactNode[];
 };
 export type ColumnDef<T extends Record<PropertyKey, any>, ID = unknown> = AutocompleteColumnDef<T, ID> | CurrencyColumnDef<T, ID> | DateColumnDef<T, ID> | NumberColumnDef<T, ID> | TextColumnDef<T, ID> | LongTextColumnDef<T, ID> | LinkColumnDef<T, ID> | SelectColumnDef<T, ID> | ActionsColumnDef<T, ID>;
+export type ColumnVisibilityModel = Record<string, boolean>;
 export type Sort = 'asc' | 'desc' | null;
 export type SortModel<T extends Record<PropertyKey, any>> = {
     [K in keyof T]: {
@@ -164,6 +166,12 @@ export type DataTableProps<T extends Record<PropertyKey, any>, GetId extends ((r
     columns: ColumnDef<T, InferredIdType<T, GetId>>[];
     pinnedColumns?: PinnedColumns;
     columnGroupingModel?: ColumnGroupingModel<T, InferredIdType<T, GetId>>;
+    /**
+     * 컬럼의 표시/숨김 상태를 제어한다. field를 key로, boolean을 value로 사용한다.
+     * false로 설정된 컬럼만 숨겨지며, 모델에 포함되지 않은 컬럼은 기본적으로 표시된다.
+     */
+    columnVisibilityModel?: ColumnVisibilityModel;
+    onColumnVisibilityModelChange?: (model: ColumnVisibilityModel) => void;
     editMode?: boolean;
     /**
      * 체크박스가 있는 경우, 체크박스를 클릭했을 때 선택된 row의 index를 지정한다.
@@ -187,6 +195,9 @@ export type DataTableProps<T extends Record<PropertyKey, any>, GetId extends ((r
         sorting: Partial<{
             sortModel: SortModel<T>[];
         }>;
+        columns: Partial<{
+            columnVisibilityModel: ColumnVisibilityModel;
+        }>;
     }>;
     pagination?: boolean;
     paginationMode?: 'client' | 'server';

package/dist/components/DataTable/utils.d.ts

@@ -3,8 +3,8 @@ export declare function extractFieldsFromGroupingModel<T extends Record<Property
 export declare function reorderColumnsByGroupingModel<T extends Record<PropertyKey, any>, ID>(columns: ColumnDef<T, ID>[], columnGroupingModel: ColumnGroupingModel<T, ID>): ColumnDef<T, ID>[];
 export declare function flattenColumnGroups<T extends Record<PropertyKey, any>, ID>(items: ColumnGroupingModel<T, ID> | ColumnDef<T, ID>[], groupPath?: string[], columnIndex?: {
     current: number;
-}): FlattenedColumn<T, ID>[];
-export declare function calculateColumnGroups<T extends Record<PropertyKey, any>, ID>(columnGroupingModel: ColumnGroupingModel<T, ID>, columns: ColumnDef<T, ID>[]): {
+}, visibleFields?: Set<string>): FlattenedColumn<T, ID>[];
+export declare function calculateColumnGroups<T extends Record<PropertyKey, any>, ID>(columnGroupingModel: ColumnGroupingModel<T, ID>, columns: ColumnDef<T, ID>[], visibleFields?: Set<string>): {
     groups: ProcessedColumnGroup[][];
     maxLevel: number;
     fieldsInGroupingModel: Set<keyof T>;

package/dist/components/RadioTileGroup/RadioTileGroup.d.ts

@@ -0,0 +1,56 @@
+import React, { ReactNode } from 'react';
+import type { SxProps } from '@mui/joy/styles/types';
+export interface RadioTileOption<T = string> {
+    value: T;
+    label: ReactNode;
+    disabled?: boolean;
+    startDecorator?: ReactNode;
+}
+export interface RadioTileGroupProps<T = string> {
+    /**
+     * @default 'sm'
+     */
+    size?: 'sm' | 'md' | 'lg';
+    options: RadioTileOption<T>[];
+    value?: T;
+    defaultValue?: T;
+    name?: string;
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    sx?: SxProps;
+    disabled?: boolean;
+    className?: string;
+    useIndicator?: boolean;
+    flex?: boolean;
+    /**
+     * 지정하지 않으면 한 row에 모든 옵션이 렌더링된다.
+     * - 특정 rows 이내로 렌더링 하고 싶으면 `columns: Math.ceil(options.length / 원하는 rows)`로 설정할 수 있다.
+     * - 수직으로 렌더링 하고 싶으면 `columns: 1`로 설정할 수 있다.
+     * - `flex` 옵션과 함께 사용할수 있다.
+     */
+    columns?: number;
+    /**
+     * @default 'center'
+     */
+    textAlign?: 'start' | 'center';
+    /**
+     * Label for the RadioTileGroup
+     */
+    label?: React.ReactNode;
+    /**
+     * Helper text for the RadioTileGroup
+     */
+    helperText?: React.ReactNode;
+    /**
+     * Whether the RadioTileGroup has an error
+     */
+    error?: boolean;
+    /**
+     * Whether the RadioTileGroup is required
+     */
+    required?: boolean;
+}
+declare function RadioTileGroup<T extends string | number = string>(props: RadioTileGroupProps<T>): React.JSX.Element;
+declare namespace RadioTileGroup {
+    var displayName: string;
+}
+export { RadioTileGroup };

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

@@ -0,0 +1,3 @@
+import { RadioTileGroup } from './RadioTileGroup';
+export * from './RadioTileGroup';
+export default RadioTileGroup;

package/dist/components/data-display/DataTable.md

@@ -865,6 +865,106 @@ const columnGroupingModel = [
 <DataTable rows={rows} columns={columns} columnGroupingModel={columnGroupingModel} />;
 ```
 
+### Column Visibility
+
+You can control which columns are visible using `columnVisibilityModel`.
+Columns set to `false` are hidden. Columns not in the model are visible by default.
+Hidden columns are completely removed from the DOM for optimal rendering performance.
+
+```tsx
+<Stack spacing={2}>
+  <Stack direction="row" spacing={1} sx={{
+    flexWrap: 'wrap'
+  }}>
+  {allColumns.map(col => <label key={col.field as string} style={{
+    display: 'flex',
+    alignItems: 'center',
+    gap: 4
+  }}>
+  <input type="checkbox" checked={visibilityModel[col.field as string] !== false} onChange={e => setVisibilityModel(prev => ({
+    ...prev,
+    [col.field as string]: e.target.checked
+  }))} />
+  {col.headerName}
+</label>)}
+</Stack>
+<DataTable rows={rows2} columns={allColumns} columnVisibilityModel={visibilityModel} onColumnVisibilityModelChange={setVisibilityModel} noWrap />
+</Stack>
+```
+
+#### Controlled Mode
+
+```tsx
+const [visibilityModel, setVisibilityModel] = useState({ fat: false });
+
+<DataTable
+  rows={rows}
+  columns={columns}
+  columnVisibilityModel={visibilityModel}
+  onColumnVisibilityModelChange={setVisibilityModel}
+/>
+```
+
+#### Uncontrolled Mode (initialState)
+
+```tsx
+<DataTable
+  rows={rows}
+  columns={columns}
+  initialState={{
+    columns: { columnVisibilityModel: { fat: false, carbs: false } },
+  }}
+/>
+```
+
+#### Column Visibility with Column Groups
+
+```tsx
+<Stack spacing={2}>
+  <Stack direction="row" spacing={1} sx={{
+    flexWrap: 'wrap'
+  }}>
+  {columns.map(col => <label key={col.field as string} style={{
+    display: 'flex',
+    alignItems: 'center',
+    gap: 4
+  }}>
+  <input type="checkbox" checked={visibilityModel[col.field as string] !== false} onChange={e => setVisibilityModel(prev => ({
+    ...prev,
+    [col.field as string]: e.target.checked
+  }))} />
+  {col.headerName}
+</label>)}
+</Stack>
+<DataTable rows={rows4} columns={columns} columnGroupingModel={[{
+  groupId: 'group1',
+  headerName: 'Group 1',
+  children: [{
+    field: 'id'
+  }, {
+    field: 'number'
+  }, {
+    field: 'string'
+  }]
+}, {
+  groupId: 'group2',
+  headerName: 'Group 2',
+  children: [{
+    field: 'date'
+  }, {
+    field: 'object'
+  }]
+}]} columnVisibilityModel={visibilityModel} onColumnVisibilityModelChange={setVisibilityModel} noWrap />
+</Stack>
+```
+
+#### Notes
+
+- Hidden columns are completely removed from the DOM for optimal performance.
+- Sorting on hidden columns is preserved — row order is maintained even if the sort column is hidden.
+- Works with column grouping: hidden columns reduce group colspan, and fully hidden groups disappear.
+- Works with pinned columns: hidden pinned columns are excluded from sticky position calculations.
+
 ### Column Resizing
 
 Setting `resizable: true` on a column allows you to adjust the column width by dragging.
@@ -895,6 +995,82 @@ const columns = [
 ];
 ```
 
+### Two-Line Headers (headerLineClamp)
+
+Setting `headerLineClamp: 2` on a column allows the header text to wrap up to 2 lines. Text exceeding 2 lines is truncated with an ellipsis, and a tooltip is displayed on hover when truncation occurs.
+
+```tsx
+<Box sx={{
+  width: 500
+}}>
+<DataTable rows={manyRows} columns={[{
+  field: 'dessert',
+  headerName: 'Dessert Name (100g serving)',
+  headerLineClamp: 2,
+  width: '120px'
+}, {
+  field: 'calories',
+  headerName: 'Calories (kcal)',
+  headerLineClamp: 2,
+  type: 'number',
+  width: '80px'
+}, {
+  field: 'fat',
+  headerName: 'Fat Content (grams)',
+  headerLineClamp: 2,
+  type: 'number',
+  width: '80px'
+}, {
+  field: 'carbs',
+  headerName: 'Total Carbohydrates (g)',
+  headerLineClamp: 2,
+  type: 'number',
+  width: '90px'
+}, {
+  field: 'protein',
+  headerName: 'Protein Amount (g)',
+  type: 'number',
+  width: '120px'
+}]} stickyHeader slotProps={{
+  background: {
+    style: {
+      height: '400px'
+    }
+  }
+}} />
+</Box>
+```
+
+```tsx
+const columns = [
+  {
+    field: 'calories',
+    headerName: 'Calories (kcal)',
+    headerLineClamp: 2,
+    type: 'number',
+    width: '80px',
+  },
+  {
+    field: 'fat',
+    headerName: 'Fat Content (grams)',
+    headerLineClamp: 2,
+    type: 'number',
+    width: '80px',
+  },
+  {
+    field: 'protein',
+    headerName: 'Protein (g)',  // no headerLineClamp — single line (default)
+    type: 'number',
+  },
+];
+```
+
+#### Notes
+
+- `headerLineClamp` is opt-in per column. Columns without it remain single-line.
+- Supported values: `1 | 2`.
+- Works with all existing features: sorting, pinning, resizing, and column grouping.
+
 ## Editing Features
 
 ### Inline Editing
@@ -1038,7 +1214,7 @@ You can use `onCellEditStart` and `onCellEditStop` to detect when editing starts
 </Typography>
 {editLog.length === 0 ? <Typography level="body-xs" textColor="text.secondary">
 No edits yet. Click on a cell to edit.
-</Typography> : editLog.map((log, i) => <Typography key={i} level="body-xs">
+</Typography> : editLog.map(log => <Typography key={log} level="body-xs">
 {log}
 </Typography>)}
 </Box>

package/dist/components/data-display/InfoSign.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-InfoSign 컴포넌트는 사용자에게 추가 정보를 제공하기 위한 툴팁 아이콘입니다. 물음표 아이콘을 클릭하거나 호버할 때 상세한 설명이나 도움말을 표시할 수 있습니다. 폼 필드, 설정 항목, 복잡한 기능에 대한 설명을 제공할 때 유용합니다.
+InfoSign is a compact tooltip-trigger component that displays a small question-mark icon. When users hover over or focus on the icon, a tooltip appears with supplementary information. It is designed to provide contextual help without cluttering the interface -- ideal for explaining form fields, settings options, table column headers, and complex metrics.
+
+The component accepts a `message` prop for the tooltip content and a `placement` prop to control where the tooltip appears relative to the icon. InfoSign keeps the main UI clean while ensuring that detailed guidance is always one interaction away.
 
 ```tsx
 <InfoSign
@@ -22,21 +24,19 @@ import { InfoSign } from '@ceed/cds';
 
 function MyComponent() {
   return (
-    <div>
-      <label>
-        복잡한 설정 항목
-        <InfoSign message="이 설정은 시스템 전체 성능에 영향을 줄 수 있습니다. 변경하기 전에 관리자와 상의하세요." />
-      </label>
-    </div>
+    <label>
+      Complex Setting
+      <InfoSign
+        message="This setting affects overall system performance. Consult an administrator before making changes."
+      />
+    </label>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-가장 기본적인 InfoSign 사용법입니다.
+The default InfoSign displays a question-mark icon that reveals a tooltip on hover or focus.
 
 ```tsx
 <InfoSign
@@ -50,104 +50,87 @@ function MyComponent() {
 ### Form Field Help
 
 ```tsx
-<FormControl>
-  <FormLabel>
-    비밀번호 복잡도
-    <InfoSign
-      message="비밀번호는 최소 8자 이상이며, 대문자, 소문자, 숫자, 특수문자를 포함해야 합니다."
-      placement="top"
-    />
-  </FormLabel>
-  <Input type="password" />
-</FormControl>
-```
-
-### Settings Explanation
+import { InfoSign } from '@ceed/cds';
+import { FormControl, FormLabel, Input } from '@ceed/cds';
 
-```tsx
-<Stack spacing={2}>
-  <Box>
-    <Typography level="title-sm">
-      자동 저장
-      <InfoSign message="이 기능을 활성화하면 5분마다 자동으로 작업 내용이 저장됩니다." placement="right" />
-    </Typography>
-    <Switch />
-  </Box>
-</Stack>
+function PasswordField() {
+  return (
+    <FormControl>
+      <FormLabel>
+        Password
+        <InfoSign
+          message="Must be at least 8 characters and include uppercase, lowercase, number, and special character."
+          placement="top"
+        />
+      </FormLabel>
+      <Input type="password" />
+    </FormControl>
+  );
+}
 ```
 
-### Complex Data Explanation
+### Table Column Header
 
 ```tsx
-<Card>
-  <CardContent>
-    <Typography level="title-md">
-      처리량 지표
-      <InfoSign
-        message="처리량은 최근 24시간 동안의 평균 요청 수를 나타냅니다. 이 값이 높을수록 시스템이 더 많은 작업을 처리하고 있다는 의미입니다."
-        placement="bottom"
-      />
-    </Typography>
-    <Typography level="h2">1,234 req/min</Typography>
-  </CardContent>
-</Card>
-```
-
-### Table Header Help
+import { InfoSign } from '@ceed/cds';
 
-```tsx
-<Table>
-  <thead>
-    <tr>
-      <th>
-        사용자 ID
-        <InfoSign message="시스템에서 자동 생성된 고유 식별자입니다." />
-      </th>
-      <th>
-        마지막 활동
-        <InfoSign message="사용자가 마지막으로 로그인하거나 활동한 시간입니다." />
-      </th>
-      <th>상태</th>
-    </tr>
-  </thead>
-</Table>
+function TableHeader() {
+  return (
+    <thead>
+      <tr>
+        <th>
+          User ID
+          <InfoSign message="Auto-generated unique identifier assigned by the system." />
+        </th>
+        <th>
+          Last Activity
+          <InfoSign message="The most recent login or action timestamp for this user." />
+        </th>
+        <th>Status</th>
+      </tr>
+    </thead>
+  );
+}
 ```
 
-## Props
-
-### placement
-
-툴팁이 나타나는 위치를 설정할 수 있습니다.
+### Dashboard Metric Explanation
 
 ```tsx
-<InfoSign placement="top" message="위쪽에 표시" />
-<InfoSign placement="bottom" message="아래쪽에 표시" />
-<InfoSign placement="left" message="왼쪽에 표시" />
-<InfoSign placement="right" message="오른쪽에 표시" />
-```
-
-### message
+import { InfoSign, Typography, Stack } from '@ceed/cds';
 
-표시할 메시지 내용입니다. 긴 텍스트도 지원합니다.
-
-```tsx
-<InfoSign message="여러 줄로 된 긴 설명문도 표시할 수 있습니다.\n줄바꿈도 지원되므로 상세한 설명을 제공할 수 있습니다." />
+function MetricCard() {
+  return (
+    <Stack spacing={1}>
+      <Typography level="title-md">
+        Throughput
+        <InfoSign
+          message="Average requests per minute over the last 24 hours. Higher values indicate greater system load."
+          placement="right"
+        />
+      </Typography>
+      <Typography level="h2">1,234 req/min</Typography>
+    </Stack>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **간결한 메시지**: 핵심 정보만 포함하여 사용자가 빠르게 이해할 수 있도록 합니다.
+- **Keep messages concise.** Tooltip messages should be 1-2 sentences that quickly answer "what does this mean?" Avoid paragraphs of text.
+  - ✔ "Maximum file size per upload. Files exceeding this limit will be rejected."
+  - ✘ A multi-paragraph explanation with examples and edge cases
 
-2. **적절한 배치**: 설명하려는 요소 바로 옆에 배치하여 연관성을 명확히 합니다.
+- **Place InfoSign directly adjacent to the element it explains.** Position it immediately after a label or header text so users can easily associate the help icon with the relevant field.
 
-3. **일관된 사용**: 비슷한 성격의 정보에는 일관되게 InfoSign을 사용합니다.
+- **Do not overuse InfoSign.** Adding a help icon to every single field creates visual noise and suggests the interface itself is too confusing. Reserve it for genuinely complex or ambiguous items.
 
-4. **과도한 사용 금지**: 모든 요소에 InfoSign을 붙이면 인터페이스가 복잡해집니다.
+- **Choose placement that avoids overlap.** Use `placement="top"` or `placement="right"` for fields near the bottom of a viewport, and `placement="bottom"` for elements near the top.
 
-## Accessibility
+- **Use InfoSign for supplementary information only.** Critical instructions or warnings should be displayed inline (e.g., with FormHelperText or Alert), not hidden behind a tooltip.
 
-- InfoSign은 키보드 탐색이 가능합니다
-- 스크린 리더가 메시지 내용을 읽을 수 있습니다
-- ARIA 라벨이 자동으로 적용됩니다
+## Accessibility
 
-InfoSign은 사용자에게 필요한 추가 정보를 제공하면서도 인터페이스를 깔끔하게 유지하는 데 도움이 되는 유용한 컴포넌트입니다.
+- InfoSign is keyboard-focusable, allowing users to trigger the tooltip using **Tab** navigation without requiring a mouse.
+- The tooltip content is announced by screen readers when the InfoSign receives focus, thanks to built-in ARIA attributes.
+- The question-mark icon serves as a universally recognized visual cue for "more information," making it intuitive for all users.
+- Ensure that the `message` text provides the same information available through other channels -- do not make the tooltip the only way to learn critical information.