etudes 3.9.1 → 4.0.0-rc.0

package/lib/Accordion.d.ts

@@ -1,9 +1,19 @@
 import React, { type ComponentType, type HTMLAttributes, type PropsWithChildren, type ReactElement, type Ref } from 'react';
-import { type ListItemProps, type ListOrientation, type ListProps, type ListSelectionMode } from './List';
+import { type CollectionItemProps, type CollectionOrientation, type CollectionProps, type CollectionSelectionMode } from './Collection';
+/**
+ * Type describing the current item selection of {@link Accordion}, composed of
+ * a dictionary whose key corresponds the section index and value corresponds to
+ * an array of selected item indices. If the selection mode of the
+ * {@link Accordion} is `single`, only one key will be present and one index in
+ * the array value.
+ */
 export type AccordionSelection = Record<number, number[]>;
-export type AccordionSection<T> = Pick<ListProps<T>, 'isSelectionTogglable' | 'itemLength' | 'itemPadding' | 'items' | 'layout' | 'numSegments'> & {
+/**
+ * Type describing the data of each section in {@link Accordion}.
+ */
+export type AccordionSection<T> = Pick<CollectionProps<T>, 'isSelectionTogglable' | 'itemLength' | 'itemPadding' | 'items' | 'layout' | 'numSegments'> & {
     /**
-     * Label for the header.
+     * Label for the section header.
      */
     label: string;
     /**
@@ -13,13 +23,39 @@ export type AccordionSection<T> = Pick<ListProps<T>, 'isSelectionTogglable' | 'i
      */
     maxVisible?: number;
 };
-export type AccordionItemProps<T> = ListItemProps<T>;
+/**
+ * Type describing the props of each `ItemComponent` provided to
+ * {@link Accordion}.
+ */
+export type AccordionItemProps<T> = CollectionItemProps<T>;
+/**
+ * Type describing the props of each `HeaderComponent` provided to
+ * {@link Accordion}.
+ */
 export type AccordionHeaderProps<I, S extends AccordionSection<I> = AccordionSection<I>> = HTMLAttributes<HTMLElement> & PropsWithChildren<{
+    /**
+     * The index of the corresponding section.
+     */
     index: number;
+    /**
+     * Indicates whether the corresponding section is collapsed.
+     */
     isCollapsed: boolean;
+    /**
+     * Data provided to the corresponding section.
+     */
     section: S;
+    /**
+     * Handler invoked to dispatch a custom event.
+     *
+     * @param name User-defined name of the custom event.
+     * @param info Optional user-defined info of the custom event.
+     */
     onCustomEvent?: (name: string, info?: any) => void;
 }>;
+/**
+ * Type describing the props of {@link Accordion}.
+ */
 export type AccordionProps<I, S extends AccordionSection<I> = AccordionSection<I>> = HTMLAttributes<HTMLDivElement> & PropsWithChildren<{
     /**
      * Specifies if expanded sections should automatically collapse upon expanding
@@ -27,25 +63,26 @@ export type AccordionProps<I, S extends AccordionSection<I> = AccordionSection<I
      */
     autoCollapseSections?: boolean;
     /**
-     * SVG markup to be put in the section header as the collapse icon.
+     * SVG markup to use as the collapse icon when a toggle button is
+     * automatically generated (when `HeaderComponent` is absent).
      */
     collapseIconSvg?: string;
     /**
-     * Indices of sections that are expanded.
+     * Indices of sections that are expanded. If specified, the component will not
+     * manage expansion states.
      */
     expandedSectionIndices?: number[];
     /**
-     * SVG markup to be put in the section header as the expand icon.
+     * SVG markup to use as the expand icon when a toggle button is automatically
+     * generated (when `HeaderComponent` is absent).
      */
     expandIconSvg?: string;
-    /**
-     * React component type to be used to generate items for each section.
-     */
-    itemComponentType?: ComponentType<AccordionItemProps<I>>;
     /**
      * Orientation of this component.
+     *
+     * @see {@link CollectionOrientation}
      */
-    orientation?: ListOrientation;
+    orientation?: CollectionOrientation;
     /**
      * Padding (in pixels) between each section.
      */
@@ -55,44 +92,60 @@ export type AccordionProps<I, S extends AccordionSection<I> = AccordionSection<I
      */
     sections: S[];
     /**
-     * Indices of selected items per section.
+     * Indices of selected items per section. If specified, the component will not
+     * manage selection state.
+     *
+     * @see {@link AccordionSelection}
      */
     selection?: AccordionSelection;
     /**
      * Selection mode of each section.
+     *
+     * @see {@link CollectionSelectionMode}
      */
-    selectionMode?: ListSelectionMode;
-    /**
-     * React component type to be used for generating headers inside the
-     * component. When absent, one will be generated automatically.
-     */
-    headerComponentType?: ComponentType<AccordionHeaderProps<I, S>>;
+    selectionMode?: CollectionSelectionMode;
     /**
      * Specifies if the component should use default styles.
      */
     useDefaultStyles?: boolean;
     /**
-     * Handler invoked when an item is activated in a section.
+     * Handler invoked when an item is activated in a section. The order of
+     * handlers invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
      */
     onActivateAt?: (itemIndex: number, sectionIndex: number) => void;
     /**
-     * Handler invoked when a section is collapsed.
+     * Handler invoked when a section is collapsed. The order of handlers invoked
+     * when any section expansion changes take place is:
+     *   1. `onCollapseSectionAt`
+     *   2. `onExpandSectionAt`
      *
      * @param sectionIndex Section index.
      */
     onCollapseSectionAt?: (sectionIndex: number) => void;
     /**
-     * Handler invoked when an item is deselected in a section.
+     * Handler invoked when an item is deselected in a section. The order of
+     * handlers invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
      */
     onDeselectAt?: (itemIndex: number, sectionIndex: number) => void;
     /**
-     * Handler invoked when a section is expanded.
+     * Handler invoked when a section is expanded. The order of handlers invoked
+     * when any section expansion changes take place is:
+     *   1. `onCollapseSectionAt`
+     *   2. `onExpandSectionAt`
      *
      * @param sectionIndex Section index.
      */
@@ -101,8 +154,8 @@ export type AccordionProps<I, S extends AccordionSection<I> = AccordionSection<I
      * Handler invoked when a custom event is dispatched from a section header.
      *
      * @param sectionIndex Index of the section which the header belongs.
-     * @param eventName Name of the dispatched event.
-     * @param eventInfo Optional info of the dispatched event.
+     * @param eventName User-defined name of the dispatched event.
+     * @param eventInfo Optional user-defined info of the dispatched event.
      */
     onHeaderCustomEvent?: (sectionIndex: number, eventName: string, eventInfo?: any) => void;
     /**
@@ -110,50 +163,82 @@ export type AccordionProps<I, S extends AccordionSection<I> = AccordionSection<I
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
-     * @param eventName Name of the dispatched event.
-     * @param eventInfo Optional info of the dispatched event.
+     * @param eventName User-defined name of the dispatched event.
+     * @param eventInfo Optional user-defined info of the dispatched event.
      */
     onItemCustomEvent?: (itemIndex: number, sectionIndex: number, eventName: string, eventInfo?: any) => void;
     /**
-     * Handler invoked when an item is selected in a section.
+     * Handler invoked when an item is selected in a section. The order of
+     * handlers invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
      */
     onSelectAt?: (itemIndex: number, sectionIndex: number) => void;
     /**
-     * Handler invoked when selected items have changed.
+     * Handler invoked when selected items have changed. The order of handlers
+     * invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param selectedIndices Dictionary of indices of selected items per section.
      */
     onSelectionChange?: (selection: AccordionSelection) => void;
+    /**
+     * Component type for generating section headers inside the component. When
+     * absent, one will be generated automatically.
+     */
+    HeaderComponent?: ComponentType<AccordionHeaderProps<I, S>>;
+    /**
+     * Component type for generating items for each section.
+     */
+    ItemComponent?: ComponentType<AccordionItemProps<I>>;
 }>;
-declare const _default: <I, S extends AccordionSection<I> = AccordionSection<I>>(props: React.HTMLAttributes<HTMLDivElement> & {
+/**
+ * A collection of selectable items laid out in sections in an accordion. Items
+ * are generated based on the provided `ItemComponent` while each section header
+ * is optionally provided by `HeaderComponent` or generated automatically.
+ *
+ * This component automatically determines if it should track selection state
+ * and expansion states internally. If the `selection` prop is provided, the
+ * component will not initialize the selection state. It will be up to its
+ * parent to provide item selection in tandem with the component's
+ * `onSelectionChange` handler. Likewise for the omission of the expansion
+ * states if `expandedSectionIndices` prop is provided.
+ */
+export declare const Accordion: <I, S extends AccordionSection<I> = AccordionSection<I>>(props: React.HTMLAttributes<HTMLDivElement> & {
     /**
      * Specifies if expanded sections should automatically collapse upon expanding
      * another section.
      */
     autoCollapseSections?: boolean | undefined;
     /**
-     * SVG markup to be put in the section header as the collapse icon.
+     * SVG markup to use as the collapse icon when a toggle button is
+     * automatically generated (when `HeaderComponent` is absent).
      */
     collapseIconSvg?: string | undefined;
     /**
-     * Indices of sections that are expanded.
+     * Indices of sections that are expanded. If specified, the component will not
+     * manage expansion states.
      */
     expandedSectionIndices?: number[] | undefined;
     /**
-     * SVG markup to be put in the section header as the expand icon.
+     * SVG markup to use as the expand icon when a toggle button is automatically
+     * generated (when `HeaderComponent` is absent).
      */
     expandIconSvg?: string | undefined;
-    /**
-     * React component type to be used to generate items for each section.
-     */
-    itemComponentType?: React.ComponentType<AccordionItemProps<I>> | undefined;
     /**
      * Orientation of this component.
+     *
+     * @see {@link CollectionOrientation}
      */
-    orientation?: ListOrientation | undefined;
+    orientation?: CollectionOrientation | undefined;
     /**
      * Padding (in pixels) between each section.
      */
@@ -163,44 +248,60 @@ declare const _default: <I, S extends AccordionSection<I> = AccordionSection<I>>
      */
     sections: S[];
     /**
-     * Indices of selected items per section.
+     * Indices of selected items per section. If specified, the component will not
+     * manage selection state.
+     *
+     * @see {@link AccordionSelection}
      */
     selection?: AccordionSelection | undefined;
     /**
      * Selection mode of each section.
+     *
+     * @see {@link CollectionSelectionMode}
      */
-    selectionMode?: ListSelectionMode | undefined;
-    /**
-     * React component type to be used for generating headers inside the
-     * component. When absent, one will be generated automatically.
-     */
-    headerComponentType?: React.ComponentType<AccordionHeaderProps<I, S>> | undefined;
+    selectionMode?: CollectionSelectionMode | undefined;
     /**
      * Specifies if the component should use default styles.
      */
     useDefaultStyles?: boolean | undefined;
     /**
-     * Handler invoked when an item is activated in a section.
+     * Handler invoked when an item is activated in a section. The order of
+     * handlers invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
      */
     onActivateAt?: ((itemIndex: number, sectionIndex: number) => void) | undefined;
     /**
-     * Handler invoked when a section is collapsed.
+     * Handler invoked when a section is collapsed. The order of handlers invoked
+     * when any section expansion changes take place is:
+     *   1. `onCollapseSectionAt`
+     *   2. `onExpandSectionAt`
      *
      * @param sectionIndex Section index.
      */
     onCollapseSectionAt?: ((sectionIndex: number) => void) | undefined;
     /**
-     * Handler invoked when an item is deselected in a section.
+     * Handler invoked when an item is deselected in a section. The order of
+     * handlers invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
      */
     onDeselectAt?: ((itemIndex: number, sectionIndex: number) => void) | undefined;
     /**
-     * Handler invoked when a section is expanded.
+     * Handler invoked when a section is expanded. The order of handlers invoked
+     * when any section expansion changes take place is:
+     *   1. `onCollapseSectionAt`
+     *   2. `onExpandSectionAt`
      *
      * @param sectionIndex Section index.
      */
@@ -209,8 +310,8 @@ declare const _default: <I, S extends AccordionSection<I> = AccordionSection<I>>
      * Handler invoked when a custom event is dispatched from a section header.
      *
      * @param sectionIndex Index of the section which the header belongs.
-     * @param eventName Name of the dispatched event.
-     * @param eventInfo Optional info of the dispatched event.
+     * @param eventName User-defined name of the dispatched event.
+     * @param eventInfo Optional user-defined info of the dispatched event.
      */
     onHeaderCustomEvent?: ((sectionIndex: number, eventName: string, eventInfo?: any) => void) | undefined;
     /**
@@ -218,26 +319,44 @@ declare const _default: <I, S extends AccordionSection<I> = AccordionSection<I>>
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
-     * @param eventName Name of the dispatched event.
-     * @param eventInfo Optional info of the dispatched event.
+     * @param eventName User-defined name of the dispatched event.
+     * @param eventInfo Optional user-defined info of the dispatched event.
      */
     onItemCustomEvent?: ((itemIndex: number, sectionIndex: number, eventName: string, eventInfo?: any) => void) | undefined;
     /**
-     * Handler invoked when an item is selected in a section.
+     * Handler invoked when an item is selected in a section. The order of
+     * handlers invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param itemIndex Item index.
      * @param sectionIndex Section index.
      */
     onSelectAt?: ((itemIndex: number, sectionIndex: number) => void) | undefined;
     /**
-     * Handler invoked when selected items have changed.
+     * Handler invoked when selected items have changed. The order of handlers
+     * invoked when any selection changes take place is:
+     *   1. `onActivateAt`
+     *   2. `onDeselectAt`
+     *   3. `onSelectAt`
+     *   4. `onSelectionChange`
      *
      * @param selectedIndices Dictionary of indices of selected items per section.
      */
     onSelectionChange?: ((selection: AccordionSelection) => void) | undefined;
+    /**
+     * Component type for generating section headers inside the component. When
+     * absent, one will be generated automatically.
+     */
+    HeaderComponent?: React.ComponentType<AccordionHeaderProps<I, S>> | undefined;
+    /**
+     * Component type for generating items for each section.
+     */
+    ItemComponent?: React.ComponentType<AccordionItemProps<I>> | undefined;
 } & {
     children?: React.ReactNode;
 } & {
     ref?: React.Ref<HTMLDivElement> | undefined;
 }) => ReactElement;
-export default _default;