useTableGroupedRows.doc.mjs

// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */

export const docs = {
  name: 'useTableGroupedRows',
  subComponentOf: 'Table',
  displayName: 'useTableGroupedRows',
  description:
    "Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group's data rows while keeping the header visible. Mirrors useTableTreeState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey, isGroupHeader}: pass the first three to Table (data, plugins, and idKey respectively), and use isGroupHeader to guard any row-level plugin or handler of your own that would otherwise treat a synthetic header as a real row.",
  props: [
    {
      name: 'data',
      type: 'T[]',
      description: 'The flat data to group.',
      required: true,
    },
    {
      name: 'groupBy',
      type: '(item: T) => string',
      description:
        'Derive the group key for a row. Rows with the same key share a section.',
      required: true,
    },
    {
      name: 'collapsedGroups',
      type: 'Set<string>',
      description: 'Set of currently-collapsed group keys.',
      required: true,
    },
    {
      name: 'onToggleGroup',
      type: '(groupKey: string) => void',
      description: 'Called with a group key when its header is toggled.',
      required: true,
    },
    {
      name: 'renderGroupHeader',
      type: '(groupKey: string, count: number, collapsed: boolean) => ReactNode',
      description:
        "Custom renderer for a group header's content (right of the chevron). Defaults to `<groupKey> (<count>)`.",
    },
    {
      name: 'getRowKey',
      type: '(item: T) => string',
      description:
        'Stable key for a real row. Falls back to a positional key when omitted.',
    },
    {
      name: 'groupOrder',
      type: 'string[]',
      description:
        'Explicit group ordering; groups not listed keep first-seen order after these.',
    },
  ],
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey, isGroupHeader}: pass the first three to Table data / plugins / idKey; use isGroupHeader to guard your own row-level plugins. Consumer owns the collapsedGroups set.',
  propDescriptions: {
    data: 'The flat data to group.',
    groupBy: "Derive a row's group key. Same key = same section.",
    collapsedGroups: 'Set of currently-collapsed group keys.',
    onToggleGroup: 'Called with the group key when a header is toggled.',
    renderGroupHeader:
      "Custom header content (right of chevron). Default '<key> (<count>)'.",
    getRowKey: 'Stable key for a real row; positional fallback when omitted.',
    groupOrder: 'Pin these group keys first; others keep first-seen order.',
  },
};