상세 행 펼치기

comins-table@0.2.2

0.2.2부터 렌더링의 표준 경로는 .render입니다. 기존 속성은 0.x에서 유지하며 1.0.0 제거 대상으로 안내합니다. 전환 규칙을 참고하십시오.

Row Expand는 flat owner business Row 바로 다음에 controlled full-width Detail 영역을 추가합니다. 애플리케이션이 expanded ID와 Detail content를 소유하며, Comins Table의 sorting, pagination, loading, movement, selection, clipboard, callback은 owner Row만 대상으로 유지됩니다.

npm run dev 실행 후 /examples/row-expand에서 fixed, automatic, viewport보다 큰 Detail 예제를 확인할 수 있습니다. 각 예제는 한 번에 하나의 owner만 확장합니다.

Public Types

export type CominsRowDetailParams<TData> = {
  row: CominsEventRow<TData>;
};

export type CominsRowDetailHeight = number | "auto";

export type CominsRowDetailProps<TData> = {
  estimatedRowDetailHeight?: number;
  expandedRowIds?: readonly CominsRowId[];
  getRowDetailHeight?: (
    params: CominsRowDetailParams<TData>,
  ) => CominsRowDetailHeight;
  isRowExpandable?: (params: CominsRowDetailParams<TData>) => boolean;
  onChangeExpandedRowIds?: (rowIds: CominsRowId[]) => void;
  rowDetail?: { render?: (
    params: CominsRowDetailParams<TData>,
  ) => React.ReactNode };
};

rowDetail.render이 flat Row Expand를 활성화합니다. 이 prop이 없으면 나머지 Detail prop도 동작하지 않습니다.

Controlled State

const [expandedRowIds, setExpandedRowIds] = useState<readonly string[]>([]);

<CominsTable
  columns={columns}
  data={rows}
  expandedRowIds={expandedRowIds}
  getRowId={(row) => row.id}
  onChangeExpandedRowIds={setExpandedRowIds}
  rowDetail={{ render: ({ row }) => <Detail row={row.data} /> }}
/>;

expandedRowIds 기본값은 빈 배열입니다. disclosure를 조작하면 onChangeExpandedRowIds가 중복을 제거한 다음 owner ID 배열을 전달하며, 애플리케이션은 그 값을 다시 prop으로 전달합니다. 기본 expandable Row에서 callback을 생략하면 read-only controlled disclosure는 전달된 상태를 표시하지만 disabled 상태가 됩니다. ID가 유효하면 Detail은 mount 상태를 유지합니다.

라이브러리는 여러 Detail을 동시에 열 수 있도록 복수 ID를 받습니다. accordion처럼 하나만 확장하려면 controlled state에 기록하기 전에 callback 값을 정규화합니다.

const [expandedRowIds, setExpandedRowIds] = useState<readonly CominsRowId[]>([]);

<CominsTable
  expandedRowIds={expandedRowIds}
  onChangeExpandedRowIds={(nextIds) => setExpandedRowIds(nextIds.slice(-1))}
/>

callback이 빈 배열을 전달하면 현재 Detail도 정상적으로 접힙니다. Row Expand Playground는 별도 Table mode prop 없이 이 애플리케이션 소유 정책을 사용합니다.

owner가 filter, pagination, loading 또는 일시적 data 변경으로 보이지 않아도 ID는 dormant 상태로 보존됩니다. 다음 callback 입력에도 포함되고 owner가 다시 나타나면 다시 유효해집니다. 현재 flat data에 owner가 존재하고 isRowExpandable이 false를 반환하지 않을 때만 ID가 유효합니다. 이는 read-only control과 별도 계약입니다. non-expandable Row는 callback과 controlled ID가 있어도 disclosure와 Detail을 모두 렌더링하지 않습니다.

Detail Height

getRowDetailHeight는 finite positive CSS pixel 또는 "auto"를 받습니다. finite positive 숫자만 fixed이며 해당 Detail은 그 inline height를 유지합니다. 값이 없거나, 잘못된 숫자이거나, "auto"이면 automatic measurement를 사용하므로 렌더링된 Detail에는 inline height가 없습니다.

<CominsTable
  estimatedRowDetailHeight={300}
  getRowDetailHeight={({ row }) => (row.id === "large" ? 480 : "auto")}
  rowDetail={{ render: ({ row }) => <Detail row={row.data} /> }}
/>

automatic Detail에 같은 width의 측정값이 없으면 finite positive estimatedRowDetailHeight를 먼저 사용하고, 그렇지 않으면 현재 resolved rowHeight를 estimate로 사용합니다. 측정값은 owner ID와 width를 기준으로 cache합니다. width가 달라지면 그 estimate로 돌아가고 shared ResizeObserver가 새 border-box height를 보고하면 갱신합니다. Fixed Detail은 observe하지 않으며 estimatedRowDetailHeight도 사용하지 않습니다.

Semantic DOM And Focus

유효한 Detail은 owner의 semantic sibling입니다.

<tr data-comins-row-data-index="0">...</tr>
<tr data-detail-for="row-id">
  <td colspan="current visible Column count">
    <div role="region" aria-labelledby="owner-disclosure-id">...</div>
  </td>
</tr>

owner disclosure는 aria-expanded를 제공합니다. aria-controls는 controlled region이 mount된 동안에만 존재합니다. region은 disclosure로 label됩니다. accessible name은 정확히 Expand <row-id> details 또는 Collapse <row-id> details입니다. native Enter와 Space activation은 유지하지만 disclosure keydown은 owner Cell/Row의 keyboard 및 clipboard 처리로 전달하지 않습니다. Detail의 interactive content는 일반 tab 순서에 포함됩니다. focus가 Detail 내부에 있을 때 controlled collapse로 unmount되면 owner disclosure로 focus가 돌아갑니다.

Detail cell은 Column hide, restore, reorder 이후의 effective visible Column 개수만큼 span합니다. 하나의 non-sticky full-width cell이며 body와 함께 horizontal scroll됩니다.

Compatibility

Surface	Row Expand 동작
Sorting	Owner와 Detail이 함께 이동하고 controlled ID는 바뀌지 않습니다.
Pagination	다른 page의 ID는 dormant 상태로 보존됩니다.
Infinite Scroll과 Lazy Load	offset, limit, threshold, count는 owner business Row만 사용합니다.
Row movement	owner Slot이 한 단위로 이동하며 Detail은 target이 아닙니다.
Row, Cell, range selection	Detail에는 Row 또는 Cell address가 없으며 range에 포함되지 않습니다.
Copy와 paste	Detail content는 clipboard source나 target이 아닙니다.
Context menu와 double-click	Owner callback은 Detail content와 disclosure event를 무시합니다.
Loading, empty, filler, Summary, infinite-loading Row	Structural Row에는 disclosure와 Detail이 없습니다.
Tree Grid	지원하지 않으며 runtime wrapper가 untyped flat Detail prop을 제거합니다.

Virtualization And Performance

같은 고정 높이의 Data Row와 접힌 Detail owner는 산술 경로를 유지합니다. Row별 지정 높이, 일반 Row 자동 높이 또는 펼쳐진 Detail은 private height index를 사용합니다. owner 자동 높이는 getRowHeight로 지정하며 Detail 높이와 독립적으로 처리합니다.

owner와 선택적 Detail은 하나의 private virtual Slot입니다. 따라서 viewport보다 큰 Detail도 outer body viewport가 해당 영역을 통과하는 동안 mount 상태를 유지하며, Detail content가 business Row로 취급되지 않습니다.

Virtual content가 body viewport보다 짧으면 마지막 Row의 하단 구분선을 유지합니다. Content가 viewport 경계에 도달한 경우에는 Cell Border를 중복하지 않고 외부 Table frame이 최종 Border를 제공합니다.

bounded panel, large list 또는 nested application widget에는 finite fixed height를 우선 사용하고 큰 inner content에는 별도 scroll이나 virtualization을 적용합니다. 실제로 측정 높이가 필요한 bounded content에만 "auto"를 사용합니다. 하나의 shared ResizeObserver가 mount된 자동 Row와 Detail block을 observe하며 고정 높이는 측정 allocation을 만들지 않습니다.

Unsupported Boundaries

• Tree Grid Row Detail은 지원하지 않습니다.
• Nested managed Detail은 지원하지 않습니다. 하나의 Detail 안에 일반 application content를 렌더링할 수 있지만 Comins Table은 두 번째 Detail hierarchy를 관리하지 않습니다.

기존 renderRowDetail은 0.x에서 호환되며 전환 가이드를 참고하십시오.

---

실행 가능한 대표 예제 · 배포 기준 원본 가이드