@ceed/ads 1.26.0 → 1.28.0

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

@@ -280,4 +280,5 @@ export declare const MotionSortIcon: import("framer-motion").CustomDomComponent<
     ref?: ((instance: SVGSVGElement | null) => void) | React.RefObject<SVGSVGElement> | null | undefined;
 }, "style" | "children" | "color" | "fontSize" | "shapeRendering" | "className" | "sx" | "viewBox" | "classes" | "htmlColor" | "inheritViewBox" | "titleAccess">>;
 export declare const DefaultLoadingOverlay: () => React.JSX.Element;
+export declare const DefaultNoRowsOverlay: () => React.JSX.Element;
 export declare const Resizer: (ref: RefObject<HTMLTableCellElement>, targetRef?: RefObject<any>) => React.JSX.Element;

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

@@ -148,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]: {
@@ -165,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를 지정한다.
@@ -188,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';
@@ -227,6 +237,7 @@ export type DataTableProps<T extends Record<PropertyKey, any>, GetId extends ((r
         toolbar?: React.ElementType;
         footer?: React.ElementType;
         loadingOverlay?: React.ElementType;
+        noRowsOverlay?: React.ElementType;
     };
     slotProps?: {
         checkbox?: Partial<{
@@ -239,6 +250,9 @@ export type DataTableProps<T extends Record<PropertyKey, any>, GetId extends ((r
         background?: Partial<{
             [key: string]: any;
         }>;
+        noRowsOverlay?: Partial<{
+            [key: string]: any;
+        }>;
     };
 } & ComponentProps<typeof Table>;
 export {};

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/data-display/DataTable.md

@@ -509,12 +509,13 @@ DataTable allows customization of various parts through `slots` and `slotProps`.
 
 ### Available Slots
 
-| Slot             | Description                  |
-| ---------------- | ---------------------------- |
-| `checkbox`       | Customize checkbox component |
-| `toolbar`        | Table top toolbar            |
-| `footer`         | Table bottom footer          |
-| `loadingOverlay` | Loading overlay              |
+| Slot             | Description                   |
+| ---------------- | ----------------------------- |
+| `checkbox`       | Customize checkbox component  |
+| `toolbar`        | Table top toolbar             |
+| `footer`         | Table bottom footer           |
+| `loadingOverlay` | Loading overlay               |
+| `noRowsOverlay`  | Empty state overlay (no rows) |
 
 ### Custom Toolbar
 
@@ -581,6 +582,154 @@ const CustomLoadingOverlay = () => (
 <DataTable rows={rows} columns={columns} loading slots={{ loadingOverlay: CustomLoadingOverlay }} />;
 ```
 
+### No Rows Overlay
+
+When `rows` is empty and `loading` is not `true`, a no rows overlay is displayed in the table body.
+
+```tsx
+<DataTable
+  onPaginationModelChange={fn()}
+  onSelectionModelChange={fn()}
+  onRowClick={fn()}
+  columns={[{
+  field: 'dessert',
+  headerName: 'Dessert (100g serving)',
+  width: '40%'
+}, {
+  field: 'calories',
+  headerName: 'Calories',
+  type: 'number'
+}, {
+  field: 'fat',
+  headerName: 'Fat (g)',
+  type: 'number'
+}, {
+  field: 'carbs',
+  headerName: 'Carbs (g)',
+  type: 'number'
+}, {
+  field: 'protein',
+  headerName: 'Protein (g)',
+  type: 'number'
+}]}
+  rows={[]}
+  noWrap
+/>
+```
+
+### Custom No Rows Overlay
+
+You can customize the empty state UI using `slots.noRowsOverlay`.
+
+```tsx
+<DataTable rows={[]} columns={tableColumns} noWrap slots={{
+  noRowsOverlay: CustomOverlay
+}} slotProps={{
+  noRowsOverlay: {
+    message: 'Custom message via slotProps'
+  }
+}} />
+```
+
+```tsx
+const CustomNoRowsOverlay = ({ message }: { message?: string }) => (
+  <Stack alignItems="center" spacing={1}>
+    <Typography level="title-md">No data available</Typography>
+    <Typography level="body-sm" textColor="text.secondary">
+      {message || 'Try adding new records.'}
+    </Typography>
+  </Stack>
+);
+
+<DataTable
+  rows={[]}
+  columns={columns}
+  slots={{ noRowsOverlay: CustomNoRowsOverlay }}
+  slotProps={{ noRowsOverlay: { message: 'Custom message via slotProps' } }}
+/>;
+```
+
+### No Rows Overlay with Checkbox
+
+The overlay correctly spans the full table width including the checkbox column.
+
+```tsx
+<DataTable
+  onPaginationModelChange={fn()}
+  onSelectionModelChange={fn()}
+  onRowClick={fn()}
+  columns={[{
+  field: 'dessert',
+  headerName: 'Dessert (100g serving)',
+  width: '40%'
+}, {
+  field: 'calories',
+  headerName: 'Calories',
+  type: 'number'
+}, {
+  field: 'fat',
+  headerName: 'Fat (g)',
+  type: 'number'
+}, {
+  field: 'carbs',
+  headerName: 'Carbs (g)',
+  type: 'number'
+}, {
+  field: 'protein',
+  headerName: 'Protein (g)',
+  type: 'number'
+}]}
+  rows={[]}
+  noWrap
+  checkboxSelection
+/>
+```
+
+### No Rows Overlay Loading Priority
+
+When `loading` is `true`, the loading overlay takes priority over the no rows overlay.
+
+```tsx
+<Stack gap={2}>
+  <Button onClick={() => setLoading(!loading)}>{loading ? 'Stop Loading' : 'Start Loading'}</Button>
+  <Typography level="body-sm">
+    {loading ? 'Loading overlay is shown (noRowsOverlay hidden)' : 'NoRowsOverlay is shown'}
+  </Typography>
+  <DataTable rows={[]} columns={tableColumns} loading={loading} noWrap slotProps={{
+    background: {
+      style: {
+        height: '300px'
+      }
+    }
+  }} />
+</Stack>
+```
+
+### Combined Custom Loading + No Rows Overlay
+
+Both `loadingOverlay` and `noRowsOverlay` slots can be customized simultaneously.
+
+```tsx
+<Stack gap={2}>
+  <Stack direction="row" gap={1} alignItems="center">
+    <Button onClick={() => setLoading(!loading)}>{loading ? 'Stop Loading' : 'Start Loading'}</Button>
+    <Typography level="body-xs" textColor="text.tertiary">
+      {loading ? 'Custom loading overlay shown' : 'Custom no rows overlay shown'}
+    </Typography>
+  </Stack>
+  <DataTable rows={[]} columns={tableColumns} loading={loading} noWrap slots={{
+    loadingOverlay: CustomLoadingOverlay,
+    noRowsOverlay: CustomNoRowsOverlay
+  }} slotProps={{
+    background: {
+      style: {
+        height: '300px'
+      }
+    }
+  }} />
+</Stack>
+```
+
 ### Custom Checkbox
 
 ```tsx
@@ -865,6 +1014,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.