@govtechsg/sgds-web-component 3.26.1 → 3.27.0-rc.0

package/types/react.d.ts

@@ -167,6 +167,42 @@ export interface SgdsAlertProps extends SgdsBaseProps {
   onSgdsHide?: SgdsEventHandler;
 }
 
+// ── AppnavProfile ─────────────────────────────────────────────────────────────
+
+export interface SgdsAppnavProfileProps extends SgdsBaseProps {
+  /** Primary text displayed next to the avatar in desktop (e.g. user name) */
+  label?: string;
+  /** Secondary text displayed below the label in desktop (e.g. agency or role) */
+  secondaryText?: string;
+  /** When true, disables the profile dropdown */
+  disabled?: boolean;
+  /** Accessible label for the profile toggle button */
+  ariaLabel?: string;
+  /** Controls dropdown close behavior. "default" auto-closes on item/outside click, "outside" closes only on outside click, "inside" prevents auto-close. */
+  close?: "default" | "outside" | "inside";
+}
+
+// ── Appnav ─────────────────────────────────────────────────────────────
+
+export interface SgdsAppnavProps extends SgdsBaseProps {
+  /** Sets the visual tone of the navigation bar */
+  tone?: "brand" | "gradient-1" | "gradient-2" | "gradient-3" | "gradient-4";
+  /** Used only for SSR to indicate the presence of the `start` slot. */
+  hasStartSlot?: boolean;
+  /** The href link for brand logo */
+  brandHref?: string;
+  /** The breakpoint, below which, the Navbar will collapse. When always the Navbar will always be expanded regardless of screen size. When never, the Navbar will always be collapsed */
+  expand?: "sm" | "md" | "lg" | "xl" | "xxl" | "always" | "never";
+  "onsgds-show"?: SgdsEventHandler;
+  onSgdsShow?: SgdsEventHandler;
+  "onsgds-after-show"?: SgdsEventHandler;
+  onSgdsAfterShow?: SgdsEventHandler;
+  "onsgds-hide"?: SgdsEventHandler;
+  onSgdsHide?: SgdsEventHandler;
+  "onsgds-after-hide"?: SgdsEventHandler;
+  onSgdsAfterHide?: SgdsEventHandler;
+}
+
 // ── Badge ─────────────────────────────────────────────────────────────
 
 export interface SgdsBadgeProps extends SgdsBaseProps {
@@ -383,96 +419,47 @@ export interface SgdsCloseButtonProps extends SgdsBaseProps {
   disabled?: boolean;
 }
 
-// ── ComboBoxOption ─────────────────────────────────────────────────────────────
+// ── DataTableCell ─────────────────────────────────────────────────────────────
 
-export interface SgdsComboBoxOptionProps extends SgdsBaseProps {
-  /** Disables the Item */
-  disabled?: boolean;
-  /** The value of the option item */
-  value?: string;
+export interface SgdsDataTableCellProps extends SgdsBaseProps {
+  /** Number of columns this cell spans. */
+  colspan?: number | undefined;
+  /** Number of rows this cell spans. */
+  rowspan?: number | undefined;
 }
 
-// ── ComboBox ─────────────────────────────────────────────────────────────
+// ── DataTableHead ─────────────────────────────────────────────────────────────
 
-export interface SgdsComboBoxProps extends SgdsBaseProps {
-  /** If true, renders multiple checkbox selection items. If false, single-select. */
-  multiSelect?: boolean;
-  /** If true, renders badge that fills width of combobox */
-  badgeFullWidth?: boolean;
-  /** If true, a clear button will be enabled on focus */
-  clearable?: boolean;
-  /** Disables native and sgds validation for the combo box. */
-  noValidate?: boolean;
-  /** Enables the asynchronous behaviour of a combo box. When true, filterFunction is ignored and filtering is done remotely. */
-  async?: boolean;
-  /** When filtering remotely and there are no results, set this to true to enable no options feedback on the menu. Applicable for async combo box only. */
-  emptyMenuAsync?: boolean;
-  /** Number of pixels from the bottom of the menu at which the sgds-scroll-end event fires. */
-  scrollBottomOffset?: number;
-  /** The function used to filter the menu list, given the user's input value. */
-  filterFunction?: (inputValue: string, item: SgdsComboBoxOptionData) => boolean;
-  /** The input's label */
-  label?: string;
-  /** The input's hint text below the label */
-  hintText?: string;
-  /** The input's name attribute */
-  name?: string;
-  /** The input's placeholder text. */
-  placeholder?: string;
-  /** Autofocus the input */
-  autofocus?: boolean;
-  /** Disables the input. */
-  disabled?: boolean;
-  /** Makes the input a required field. */
-  required?: boolean;
-  /** Sets the loading state of the component */
-  loading?: boolean;
-  /** IMPORTANT:
-We still expose `.value` externally, but this is now the underlying ID or data
-(e.g. 1, 2, 'abc', ...), not the label that appears in the input box. */
-  value?: string;
-  displayValue?: string;
-  /** Allows invalidFeedback, invalid and valid styles to be visible with the input */
-  hasFeedback?: boolean;
-  /** Feedback text for error state when validated */
-  invalidFeedback?: string;
-  /** Marks the component as invalid. Replace the pseudo :invalid selector. */
-  invalid?: boolean;
-  /** Controlling of autocomplete behaviour */
-  autocomplete?: string;
-  /** The list of items to display in the dropdown.
-`interface SgdsComboBoxItemData {
-label: string;
-value: string;
-}` */
-  menuList?: SgdsOptionData[];
-  /** Returns the ValidityState object */
-  validity?: ValidityState;
-  /** Returns the validation message based on the ValidityState */
-  validationMessage?: string;
-  /** Additional configuration to pass to Floating UI. */
-  floatingOpts?: { placement?: Placement; middleware?: Array<Middleware> };
-  hidden?: boolean;
-  /** When true, dropdown menu shows on first load */
-  menuIsOpen?: boolean;
-  /** Makes the input readonly. */
-  readonly?: boolean;
-  "onsgds-select"?: SgdsEventHandler;
-  onSgdsSelect?: SgdsEventHandler;
-  "onsgds-change"?: SgdsEventHandler;
-  onSgdsChange?: SgdsEventHandler;
-  "onsgds-input"?: (event: CustomEvent<ISgdsComboBoxInputEventDetail>) => void;
-  onSgdsInput?: (event: CustomEvent<ISgdsComboBoxInputEventDetail>) => void;
-  "onsgds-focus"?: SgdsEventHandler;
-  onSgdsFocus?: SgdsEventHandler;
-  "onsgds-blur"?: SgdsEventHandler;
-  onSgdsBlur?: SgdsEventHandler;
-  "onsgds-invalid"?: SgdsEventHandler;
-  onSgdsInvalid?: SgdsEventHandler;
-  "onsgds-valid"?: SgdsEventHandler;
-  onSgdsValid?: SgdsEventHandler;
-  "onsgds-scroll-end"?: SgdsEventHandler;
-  onSgdsScrollEnd?: SgdsEventHandler;
+export interface SgdsDataTableHeadProps extends SgdsBaseProps {
+  /** Sets the column width. */
+  width?: string | undefined;
+  /** Number of columns this cell spans. */
+  colspan?: number | undefined;
+  /** Number of rows this cell spans. */
+  rowspan?: number | undefined;
+  /** Text alignment for the header content. */
+  textAlign?: "left" | "right";
+  /** Current sort direction for this column. */
+  ariasort?: "ascending" | "descending" | "none" | "other" | undefined;
+  /** When true, clicking this header cycles through ascending → descending → none sort. */
+  sorting?: boolean;
+  /** Column key emitted in the row's internal sort payload, used to identify which column to sort. */
+  sortKey?: string;
+}
+
+// ── DataTableRow ─────────────────────────────────────────────────────────────
+
+export interface SgdsDataTableRowProps extends SgdsBaseProps {
+  /** Arbitrary data associated with this row. Returned in event detail on row selection. */
+  rowData?: Record<string, unknown>;
+  /** When true, the row has an expandable content area toggled by a chevron. */
+  expand?: boolean;
+  /** When true, the expandable content area is open. */
+  open?: boolean;
+  /** When true, the row is checked. */
+  checked?: boolean;
+  /** The checkbox rendered inside this row, if `showCheckbox` is true. */
+  checkbox?: SgdsCheckbox | null;
   "onsgds-show"?: SgdsEventHandler;
   onSgdsShow?: SgdsEventHandler;
   "onsgds-after-show"?: SgdsEventHandler;
@@ -483,6 +470,40 @@ value: string;
   onSgdsAfterHide?: SgdsEventHandler;
 }
 
+// ── DataTable ─────────────────────────────────────────────────────────────
+
+export interface SgdsDataTableProps extends SgdsBaseProps {
+  /** If true, renders a checkbox column for row selection. */
+  multiSelect?: boolean;
+  /** Total number of data items (for server-side pagination). */
+  dataLength?: number;
+  /** Current page (1-based). */
+  currentPage?: number;
+  /** Number of rows per page. */
+  itemsPerPage?: number;
+  /** Custom text shown on the footer's left side. */
+  footerText?: string;
+  /** If true, hides the footer (summary text and pagination controls). */
+  hideFooter?: boolean;
+  /** When true, shows a loading state and hides body rows. */
+  isLoading?: boolean;
+  /** When true, emits sort events for external handling instead of local sorting. */
+  serverSort?: boolean;
+  /** Controls the CSS `table-layout` algorithm.
+Use "auto" to let the browser size columns based on content, or "fixed" to distribute column widths evenly regardless of content. */
+  layout?: "auto" | "fixed";
+  /** Pagination mode. `client` (default) slices rows and renders pagination controls.
+`server` renders all slotted rows as-is — the caller is responsible for passing
+the correct page of data and handling `sgds-page-change` externally. */
+  mode?: "client" | "server";
+  "onsgds-row-select"?: SgdsEventHandler;
+  onSgdsRowSelect?: SgdsEventHandler;
+  "onsgds-sort"?: SgdsEventHandler;
+  onSgdsSort?: SgdsEventHandler;
+  "onsgds-page-change"?: SgdsEventHandler;
+  onSgdsPageChange?: SgdsEventHandler;
+}
+
 // ── Datepicker ─────────────────────────────────────────────────────────────
 
 export interface SgdsDatepickerProps extends SgdsBaseProps {
@@ -575,6 +596,106 @@ export interface SgdsDescriptionListProps extends SgdsBaseProps {
   bordered?: boolean;
 }
 
+// ── ComboBoxOption ─────────────────────────────────────────────────────────────
+
+export interface SgdsComboBoxOptionProps extends SgdsBaseProps {
+  /** Disables the Item */
+  disabled?: boolean;
+  /** The value of the option item */
+  value?: string;
+}
+
+// ── ComboBox ─────────────────────────────────────────────────────────────
+
+export interface SgdsComboBoxProps extends SgdsBaseProps {
+  /** If true, renders multiple checkbox selection items. If false, single-select. */
+  multiSelect?: boolean;
+  /** If true, renders badge that fills width of combobox */
+  badgeFullWidth?: boolean;
+  /** If true, a clear button will be enabled on focus */
+  clearable?: boolean;
+  /** Disables native and sgds validation for the combo box. */
+  noValidate?: boolean;
+  /** Enables the asynchronous behaviour of a combo box. When true, filterFunction is ignored and filtering is done remotely. */
+  async?: boolean;
+  /** When filtering remotely and there are no results, set this to true to enable no options feedback on the menu. Applicable for async combo box only. */
+  emptyMenuAsync?: boolean;
+  /** Number of pixels from the bottom of the menu at which the sgds-scroll-end event fires. */
+  scrollBottomOffset?: number;
+  /** The function used to filter the menu list, given the user's input value. */
+  filterFunction?: (inputValue: string, item: SgdsComboBoxOptionData) => boolean;
+  /** The input's label */
+  label?: string;
+  /** The input's hint text below the label */
+  hintText?: string;
+  /** The input's name attribute */
+  name?: string;
+  /** The input's placeholder text. */
+  placeholder?: string;
+  /** Autofocus the input */
+  autofocus?: boolean;
+  /** Disables the input. */
+  disabled?: boolean;
+  /** Makes the input a required field. */
+  required?: boolean;
+  /** Sets the loading state of the component */
+  loading?: boolean;
+  /** IMPORTANT:
+We still expose `.value` externally, but this is now the underlying ID or data
+(e.g. 1, 2, 'abc', ...), not the label that appears in the input box. */
+  value?: string;
+  displayValue?: string;
+  /** Allows invalidFeedback, invalid and valid styles to be visible with the input */
+  hasFeedback?: boolean;
+  /** Feedback text for error state when validated */
+  invalidFeedback?: string;
+  /** Marks the component as invalid. Replace the pseudo :invalid selector. */
+  invalid?: boolean;
+  /** Controlling of autocomplete behaviour */
+  autocomplete?: string;
+  /** The list of items to display in the dropdown.
+`interface SgdsComboBoxItemData {
+label: string;
+value: string;
+}` */
+  menuList?: SgdsOptionData[];
+  /** Returns the ValidityState object */
+  validity?: ValidityState;
+  /** Returns the validation message based on the ValidityState */
+  validationMessage?: string;
+  /** Additional configuration to pass to Floating UI. */
+  floatingOpts?: { placement?: Placement; middleware?: Array<Middleware> };
+  hidden?: boolean;
+  /** When true, dropdown menu shows on first load */
+  menuIsOpen?: boolean;
+  /** Makes the input readonly. */
+  readonly?: boolean;
+  "onsgds-select"?: SgdsEventHandler;
+  onSgdsSelect?: SgdsEventHandler;
+  "onsgds-change"?: SgdsEventHandler;
+  onSgdsChange?: SgdsEventHandler;
+  "onsgds-input"?: (event: CustomEvent<ISgdsComboBoxInputEventDetail>) => void;
+  onSgdsInput?: (event: CustomEvent<ISgdsComboBoxInputEventDetail>) => void;
+  "onsgds-focus"?: SgdsEventHandler;
+  onSgdsFocus?: SgdsEventHandler;
+  "onsgds-blur"?: SgdsEventHandler;
+  onSgdsBlur?: SgdsEventHandler;
+  "onsgds-invalid"?: SgdsEventHandler;
+  onSgdsInvalid?: SgdsEventHandler;
+  "onsgds-valid"?: SgdsEventHandler;
+  onSgdsValid?: SgdsEventHandler;
+  "onsgds-scroll-end"?: SgdsEventHandler;
+  onSgdsScrollEnd?: SgdsEventHandler;
+  "onsgds-show"?: SgdsEventHandler;
+  onSgdsShow?: SgdsEventHandler;
+  "onsgds-after-show"?: SgdsEventHandler;
+  onSgdsAfterShow?: SgdsEventHandler;
+  "onsgds-hide"?: SgdsEventHandler;
+  onSgdsHide?: SgdsEventHandler;
+  "onsgds-after-hide"?: SgdsEventHandler;
+  onSgdsAfterHide?: SgdsEventHandler;
+}
+
 // ── Divider ─────────────────────────────────────────────────────────────
 
 export interface SgdsDividerProps extends SgdsBaseProps {
@@ -623,6 +744,8 @@ export interface SgdsDropdownItemProps extends SgdsBaseProps {
   active?: boolean;
   /** Disables the SgdsMainnavItem */
   disabled?: boolean;
+  /** When true, removes interactive styles (hover, cursor) for non-navigational display items */
+  readonly?: boolean;
   /** Forwards aria-label to the inner clickable element for accessibility */
   ariaLabel?: string;
 }
@@ -945,17 +1068,32 @@ export interface SgdsMainnavItemProps extends SgdsBaseProps {
   disabled?: boolean;
 }
 
+// ── MainnavProfile ─────────────────────────────────────────────────────────────
+
+export interface SgdsMainnavProfileProps extends SgdsBaseProps {
+  /** Primary text displayed next to the avatar in desktop (e.g. user name) */
+  label?: string;
+  /** Secondary text displayed below the label in desktop (e.g. agency or role) */
+  secondaryText?: string;
+  /** When true, disables the profile dropdown */
+  disabled?: boolean;
+  /** Accessible label for the profile toggle button */
+  ariaLabel?: string;
+  /** Controls dropdown close behavior. "default" auto-closes on item/outside click, "outside" closes only on outside click, "inside" prevents auto-close. */
+  close?: "default" | "outside" | "inside";
+}
+
 // ── Mainnav ─────────────────────────────────────────────────────────────
 
 export interface SgdsMainnavProps extends SgdsBaseProps {
   /** Used only for SSR to indicate the presence of the `non-collapsible` slot. */
   hasNonCollapsibleSlot?: boolean;
+  /** When true, removes max-width constraint to allow content to stretch full screen width */
+  fluid?: boolean;
   /** The href link for brand logo */
   brandHref?: string;
   /** The breakpoint, below which, the Navbar will collapse. When always the Navbar will always be expanded regardless of screen size. When never, the Navbar will always be collapsed */
   expand?: "sm" | "md" | "lg" | "xl" | "xxl" | "always" | "never";
-  /** When true, removes max-width constraint to allow content to stretch full screen width */
-  fluid?: boolean;
   "onsgds-show"?: SgdsEventHandler;
   onSgdsShow?: SgdsEventHandler;
   "onsgds-after-show"?: SgdsEventHandler;
@@ -1739,6 +1877,8 @@ declare module "react" {
       "sgds-accordion": React.DetailedHTMLProps<SgdsAccordionProps, HTMLElement>;
       "sgds-alert-link": React.DetailedHTMLProps<SgdsAlertLinkProps, HTMLElement>;
       "sgds-alert": React.DetailedHTMLProps<SgdsAlertProps, HTMLElement>;
+      "sgds-appnav-profile": React.DetailedHTMLProps<SgdsAppnavProfileProps, HTMLElement>;
+      "sgds-appnav": React.DetailedHTMLProps<SgdsAppnavProps, HTMLElement>;
       "sgds-badge": React.DetailedHTMLProps<SgdsBadgeProps, HTMLElement>;
       "sgds-breadcrumb-item": React.DetailedHTMLProps<SgdsBreadcrumbItemProps, HTMLElement>;
       "sgds-breadcrumb": React.DetailedHTMLProps<SgdsBreadcrumbProps, HTMLElement>;
@@ -1747,11 +1887,15 @@ declare module "react" {
       "sgds-checkbox-group": React.DetailedHTMLProps<SgdsCheckboxGroupProps, HTMLElement>;
       "sgds-checkbox": React.DetailedHTMLProps<SgdsCheckboxProps, HTMLElement>;
       "sgds-close-button": React.DetailedHTMLProps<SgdsCloseButtonProps, HTMLElement>;
-      "sgds-combo-box-option": React.DetailedHTMLProps<SgdsComboBoxOptionProps, HTMLElement>;
-      "sgds-combo-box": React.DetailedHTMLProps<SgdsComboBoxProps, HTMLElement>;
+      "sgds-data-table-cell": React.DetailedHTMLProps<SgdsDataTableCellProps, HTMLElement>;
+      "sgds-data-table-head": React.DetailedHTMLProps<SgdsDataTableHeadProps, HTMLElement>;
+      "sgds-data-table-row": React.DetailedHTMLProps<SgdsDataTableRowProps, HTMLElement>;
+      "sgds-data-table": React.DetailedHTMLProps<SgdsDataTableProps, HTMLElement>;
       "sgds-datepicker": React.DetailedHTMLProps<SgdsDatepickerProps, HTMLElement>;
       "sgds-description-list-group": React.DetailedHTMLProps<SgdsDescriptionListGroupProps, HTMLElement>;
       "sgds-description-list": React.DetailedHTMLProps<SgdsDescriptionListProps, HTMLElement>;
+      "sgds-combo-box-option": React.DetailedHTMLProps<SgdsComboBoxOptionProps, HTMLElement>;
+      "sgds-combo-box": React.DetailedHTMLProps<SgdsComboBoxProps, HTMLElement>;
       "sgds-divider": React.DetailedHTMLProps<SgdsDividerProps, HTMLElement>;
       "sgds-drawer": React.DetailedHTMLProps<SgdsDrawerProps, HTMLElement>;
       "sgds-dropdown-item": React.DetailedHTMLProps<SgdsDropdownItemProps, HTMLElement>;
@@ -1768,6 +1912,7 @@ declare module "react" {
       "sgds-link": React.DetailedHTMLProps<SgdsLinkProps, HTMLElement>;
       "sgds-mainnav-dropdown": React.DetailedHTMLProps<SgdsMainnavDropdownProps, HTMLElement>;
       "sgds-mainnav-item": React.DetailedHTMLProps<SgdsMainnavItemProps, HTMLElement>;
+      "sgds-mainnav-profile": React.DetailedHTMLProps<SgdsMainnavProfileProps, HTMLElement>;
       "sgds-mainnav": React.DetailedHTMLProps<SgdsMainnavProps, HTMLElement>;
       "sgds-masthead": React.DetailedHTMLProps<SgdsMastheadProps, HTMLElement>;
       "sgds-modal": React.DetailedHTMLProps<SgdsModalProps, HTMLElement>;
@@ -1822,6 +1967,8 @@ declare global {
     "sgds-accordion": HTMLElement;
     "sgds-alert-link": HTMLElement;
     "sgds-alert": HTMLElement;
+    "sgds-appnav-profile": HTMLElement;
+    "sgds-appnav": HTMLElement;
     "sgds-badge": HTMLElement;
     "sgds-breadcrumb-item": HTMLElement;
     "sgds-breadcrumb": HTMLElement;
@@ -1830,11 +1977,15 @@ declare global {
     "sgds-checkbox-group": HTMLElement;
     "sgds-checkbox": HTMLElement;
     "sgds-close-button": HTMLElement;
-    "sgds-combo-box-option": HTMLElement;
-    "sgds-combo-box": HTMLElement;
+    "sgds-data-table-cell": HTMLElement;
+    "sgds-data-table-head": HTMLElement;
+    "sgds-data-table-row": HTMLElement;
+    "sgds-data-table": HTMLElement;
     "sgds-datepicker": HTMLElement;
     "sgds-description-list-group": HTMLElement;
     "sgds-description-list": HTMLElement;
+    "sgds-combo-box-option": HTMLElement;
+    "sgds-combo-box": HTMLElement;
     "sgds-divider": HTMLElement;
     "sgds-drawer": HTMLElement;
     "sgds-dropdown-item": HTMLElement;
@@ -1851,6 +2002,7 @@ declare global {
     "sgds-link": HTMLElement;
     "sgds-mainnav-dropdown": HTMLElement;
     "sgds-mainnav-item": HTMLElement;
+    "sgds-mainnav-profile": HTMLElement;
     "sgds-mainnav": HTMLElement;
     "sgds-masthead": HTMLElement;
     "sgds-modal": HTMLElement;