# Composed Components

Lightweight index for quickly finding the right component and its import path. Prop details live in each component's `types.ts` with JSDoc comments — check there for full API reference.

---

## Table of Contents

### General
- [AvatarSwitcherCard](#avatarswitchercard)
- [BadgeCountButton](#badgecountbutton)
- [Breakdown](#breakdown)
- [Category](#category)
- [CheckboxAutocomplete](#checkboxautocomplete)
- [CollapsibleAutocompleteSelector](#collapsibleautocompleteselector)
- [CollapsibleInfoSidebar](#collapsibleinfosidebar)
- [CollapsibleSelectionList](#collapsibleselectionlist)
- [ConditionGroup](#conditiongroup)
- [ConditionLine](#conditionline)
- [ConfettiBackground](#confettibackground)
- [CoverPictureUploader](#coverpictureuploader)
- [CroppingModal](#croppingmodal)
- [DatePeriodSelector](#dateperiodselector)
- [DatePickerWithOptions](#datepickerwithoptions)
- [FileUploaderButton](#fileuploaderbutton)
- [FilterAccordion](#filteraccordion)
- [FilterAccordionContent](#filteraccordioncontent)
- [Filters](#filters)
- [GlobalStyles](#globalstyles)
- [HTMLBody](#htmlbody)
- [IconPicker](#iconpicker)
- [Image](#image)
- [InfiniteListLoader](#infinitelistloader)
- [LibrariesSidebar](#librariessidebar)
- [LikertSlider](#likertslider)
- [MenuList](#menulist)
- [MenuListItems](#menulistitems)
- [MidCircle](#midcircle)
- [PdfViewer](#pdfviewer)
- [PdfVisualizer](#pdfvisualizer)
- [Pie](#pie)
- [ProgressCircle](#progresscircle)
- [Property](#property)
- [QuestionListItem](#questionlistitem)
- [RadioButtonGroup](#radiobuttongroup)
- [RadioGroup](#radiogroup)
- [RadioInput](#radioinput)
- [SeeMoreText](#seemoretext)
- [SelectableListItem](#selectablelistitem)
- [SelectionCard](#selectioncard)
- [SidebarContentLayout](#sidebarcontentlayout)
- [SortableList](#sortablelist)
- [SortableListComposition](#sortablelistcomposition)
- [StateCard](#statecard)
- [SubSidebar](#subsidebar)
- [SwitcherCard](#switchercard)
- [TableSkeleton](#tableskeleton)
- [Tag](#tag)
- [TaskFocusLayout](#taskfocuslayout)
- [TimePicker](#timepicker)
- [TutorialModal](#tutorialmodal)
- [TypographyOverflowTooltip](#typographyoverflowtooltip)
- [UserAvatar](#useravatar)
- [UserCard](#usercard)
- [VirtualizedList](#virtualizedlist)
- [WeekMonthSelector](#weekmonthselector)

### Inputs
- [UserAutoComplete](#userautocomplete)

### Pagination
- [PaginationController](#paginationcontroller)
- [SearchBarController](#searchbarcontroller)

### Charts
- [BreakdownChart](#breakdownchart)
- [MidCircleChart](#midcirclechart)
- [PieChart](#piechart)
- [ProgressCircleChart](#progresscirclechart)
- [SingleStackedBarChart](#singlestackedbarchart)
- [TreemapChart](#treemapchart)

### Domain
- [audience/](#audience)
- [auth/](#auth)
- [dynamic-forms/](#dynamic-forms)
- [files/](#files)
- [learning/](#learning)
- [peopleExperience/](#peopleexperience)
- [posts/](#posts)
- [profile/](#profile)
- [sign/](#sign)

---

## AvatarSwitcherCard
- **Import:** `./AvatarSwitcherCard`
- **Description:** A card combining a Tabler icon avatar, title, description, toggle switch, optional pills, and icon-button actions — use it for feature toggles or setting entries.

## BadgeCountButton
- **Import:** `./BadgeCountButton`
- **Description:** A MUI Button with a numeric badge overlay — use it to show a count (e.g. active filters) on a button.

## Breakdown
- **Import:** `./Breakdown`
- **Description:** Horizontal stacked-bar visualization of labeled numeric values — use it to show proportional breakdowns at a glance.

## Category
- **Import:** `./Category`
- **Description:** A selectable chip-like item with an icon and label — use it to represent a category that can be toggled on/off.

## CheckboxAutocomplete
- **Import:** `./CheckboxAutocomplete`
- **Description:** A search-driven multi-select field that shows results as checkboxes and selected items as chips — use it when users need to pick multiple items from a searchable list.

## CollapsibleAutocompleteSelector
- **Import:** `./CollapsibleAutocompleteSelector`
- **Description:** An accordion-wrapped searchable multi-select backed by an infinite React Query — use it for large, paginated datasets inside filter panels.
- **Notes:** Supports controlled/uncontrolled mode, react-hook-form via `fieldName`, select-all, virtualization, and a selection limit.

## CollapsibleInfoSidebar
- **Import:** `./CollapsibleInfoSidebar`
- **Description:** A vertically-stacked icon-triggered sidebar that expands to reveal contextual content panels — use it for help, info, or detail sidebars that should stay out of the way.

## CollapsibleSelectionList
- **Import:** `./CollapsibleSelectionList`
- **Description:** An accordion with a searchable, virtualizable checklist inside — use it for filter or selection panels with a manageable item count.

## ConditionGroup
- **Import:** `./ConditionGroup`
- **Description:** A card containing multiple `ConditionLine` rows with add/delete controls — use it to let users build multi-condition filter expressions.
- **Form variant:** `./ConditionGroup/form`

## ConditionLine
- **Import:** `./ConditionLine`
- **Description:** A single condition row with join operator, field selector, condition operator, and value selector — use it as a building block inside `ConditionGroup`.
- **Form variant:** `./ConditionLine/form`
- **Notes:** Exports `ConditionOperator` (IS, IS_NOT, IS_IN, CONTAINS, etc.) and `JoinOperator` (AND, OR) enums.

## ConfettiBackground
- **Import:** `./ConfettiBackground`
- **Description:** A decorative banner with an optional cover picture, background color, confetti animation, and points text — use it for celebration or reward moments.

## CoverPictureUploader
- **Import:** `./CoverPictureUploader`
- **Description:** An image upload field that opens a cropping modal and returns both original and cropped files — use it anywhere a cover or banner image is needed.
- **Form variant:** `./CoverPictureUploader/form`

## CroppingModal
- **Import:** `./CroppingModal`
- **Description:** A modal that lets users crop and zoom an uploaded image before saving — use it directly when you need custom crop flows outside `CoverPictureUploader`.

## DatePeriodSelector
- **Import:** `./DatePeriodSelector`
- **Description:** A dual date-picker (from/to) with predefined period shortcuts (daily, weekly, monthly, custom) — use it for date-range filters on dashboards or reports.

## DatePickerWithOptions
- **Import:** `./DatePickerWithOptions`
- **Description:** Radio-button options combined with optional start/end date pickers — use it for scheduling forms where the user first picks a timing option then sets dates.
- **Notes:** Uses react-hook-form internally; wrap in a `FormProvider`.

## FileUploaderButton
- **Import:** `./FileUploaderButton`
- **Description:** A button that triggers a native file-input — use it as a lightweight alternative to `CoverPictureUploader` when no cropping is needed.

## FilterAccordion
- **Import:** `./FilterAccordion`
- **Description:** An accordion whose collapsed header previews selected filter items — use it as a container for individual filter groups inside a filter panel.

## FilterAccordionContent
- **Import:** `./FilterAccordionContent`
- **Description:** The inner content of a filter accordion: searchbar, checkboxes, optional select-all, and infinite-scroll trigger — use it inside `FilterAccordion`.

## Filters
- **Import:** `./Filters/FiltersButton`
- **Description:** A button with an active-count badge and a clear action — use it as the entry point to open a filter side panel.

## GlobalStyles
- **Import:** `./GlobalStyles`
- **Description:** Bakes in a shared CSS reset (box-sizing, font-smoothing, 100% height on html/body/#root) and accepts an optional `additionalStyles` prop for app-specific additions — use it as the single global styles entry point in any consumer app.

## HTMLBody
- **Import:** `./HTMLBody`
- **Description:** Safely renders a raw HTML string with optional video-download support — use it to display rich-text content from the API.

## IconPicker
- **Import:** `./IconPicker`
- **Description:** A trigger button that opens a picker for Tabler icons, emojis, or uploaded images — use it wherever users must choose an icon to represent an entity.
- **Form variant:** `./IconPicker/form`

## Image
- **Import:** `./Image`
- **Description:** An image with enforced aspect ratio, skeleton loading, and fallback URL — use it instead of a plain `<img>` whenever consistent proportions and loading states are needed.

## InfiniteListLoader
- **Import:** `./InfiniteListLoader`
- **Description:** An IntersectionObserver-backed "load more" button that fires when it enters the scroll container — use it at the bottom of paginated lists.

## LibrariesSidebar
- **Import:** `./LibrariesSidebar`
- **Description:** A tree-structured sidebar for navigating and reordering library articles or sections — use it for knowledge-base or content library navigation.

## LikertSlider
- **Import:** `./LikertSlider`
- **Description:** An MUI Slider styled for Likert-scale survey questions, with optional inversion — use it inside survey forms.
- **Form variant:** `./LikertSlider/form`

## MenuList
- **Import:** `./MenuList`
- **Description:** A three-dot (or custom) icon-button that opens a MUI Menu with optional nested items — use it for contextual action menus on cards or rows.

## MenuListItems
- **Import:** `./MenuListItems`
- **Description:** A trigger button that opens a searchable multi-select menu — use it when an inline dropdown must support search and multi-selection.
- **Form variant:** `./MenuListItems/form`

## MidCircle
- **Import:** `./MidCircle`
- **Description:** A half-donut progress chart with title, description, and loading skeleton — use it to display a metric as a percentage arc.

## PdfViewer
- **Import:** `./PdfViewer`
- **Description:** A PDF viewer with page navigation, fullscreen, and an optional "finish reading" callback — use it when users must consume a document and you need to track completion.

## PdfVisualizer
- **Import:** `./PdfVisualizer`
- **Description:** A scrollable PDF viewer with an optional thumbnail sidebar — use it for richer PDF reading experiences where a bar-style navigator is not enough.

## Pie
- **Import:** `./Pie`
- **Description:** A pie chart widget with title, legend, and loading skeleton — use it to show proportional data with labeled slices.

## ProgressCircle
- **Import:** `./ProgressCircle`
- **Description:** A full-circle progress chart with title, description, and loading skeleton — use it to display a completion percentage.

## Property
- **Import:** `./Property`
- **Description:** An icon + label + value display row with multiple size variants — use it to render metadata fields in detail panels or cards.

## QuestionListItem
- **Import:** `./QuestionListItem`
- **Description:** A list item for displaying a survey question with index, type description, pills, and actions — designed to be used as `ItemComponent` inside `SortableList`.

## RadioButtonGroup
- **Import:** `./RadioButtonGroup`
- **Description:** A group of styled radio buttons rendered from an options array — use it when a compact horizontal radio layout is needed; primary usage is via the form variant.
- **Form variant:** `./RadioButtonGroup/form`

## RadioGroup
- **Import:** `./RadioGroup`
- **Description:** A vertical radio group built on `SelectionCard` items — use it for option selection where each choice deserves card-level emphasis.
- **Form variant:** `./RadioGroup/form`

## RadioInput
- **Import:** `./RadioInput`
- **Description:** A labeled radio group with optional per-option descriptions — use it for inline option selection in forms.
- **Form variant:** `./RadioInput/form`

## SeeMoreText
- **Import:** `./SeeMoreText`
- **Description:** A text block that clamps to N lines with a "see more / see less" toggle — use it for long descriptions in cards or list items.

## SelectableListItem
- **Import:** `./SelectableListItem`
- **Description:** A list item with a checkbox and selectable state — use it to build multi-select lists where each row can be individually toggled.

## SelectionCard
- **Import:** `./SelectionCard`
- **Description:** A bordered card that acts as a large radio/checkbox toggle — use it when choices need a card-level click target.
- **Form variant:** `./SelectionCard/form`

## SidebarContentLayout
- **Import:** `./SidebarContentLayout`
- **Description:** A two-column layout with a collapsible navigation sidebar on one side and main content on the other — use it for settings-style pages with multiple sections.

## SortableList
- **Import:** `./SortableList`
- **Description:** A drag-and-drop reorderable list powered by dnd-kit — use it when items in a list need to be manually reordered by the user.
- **Notes:** Pass `dragByHandler` to restrict dragging to a handle; `ItemComponent` receives `isDragging` and `dragHandleButton` props.

## SortableListComposition
- **Import:** `./SortableListComposition`
- **Description:** A composable drag-and-drop API (`Root`, `Container`, `Item`, `DragHandle`) for building custom multi-container sortable layouts — use it when `SortableList` is too constrained.

## StateCard
- **Import:** `./StateCard`
- **Description:** An empty/error state card with an avatar icon, title, description, and optional action button — use it as the fallback UI for empty lists or failed loads.
- **Notes:** Configure via `slotProps`; the legacy flat props are deprecated.

## SubSidebar
- **Import:** `./SubSidebar`
- **Description:** A collapsible secondary navigation sidebar with nested sections and accordion groups — use it for module-level navigation inside a page.

## SwitcherCard
- **Import:** `./SwitcherCard`
- **Description:** A card with a toggle switch that reveals collapsible child content when enabled — use it for optional settings blocks.
- **Form variant:** `./SwitcherCard/form`

## TableSkeleton
- **Import:** `./TableSkeleton`
- **Description:** A skeleton placeholder shaped like a data table — use it while table data is loading.

## Tag
- **Import:** `./Tag`
- **Description:** A small colored label chip — use it to display status, category, or classification badges.
- **Notes:** Color is controlled via the `TagColorVariant` enum (import from `./Tag/types`).

## TaskFocusLayout
- **Import:** `./TaskFocusLayout`
- **Description:** A full-page focused layout with a header (title + close button) and a content area — use it for task-completion flows that should feel separate from the main app chrome.

## TimePicker
- **Import:** `./TimePicker`
- **Description:** A time input field with minute-step control, timezone support, and error state — use it for time-of-day selection in forms.
- **Form variant:** `./TimePicker/form`

## TutorialModal
- **Import:** `./TutorialModal`
- **Description:** A multi-step tutorial modal controlled via the `useTutorialModal` hook — use it to onboard users through a feature with step images and navigation.
- **Notes:** Use `useTutorialModal({ steps, texts, callbacks })` to get `{ modal, showModal }`; render `{modal}` in JSX and call `showModal()` to open it.

## TypographyOverflowTooltip
- **Import:** `./TypographyOverflowTooltip`
- **Description:** A tooltip that only appears when its text child is truncated/overflowing — use it on table cells or card titles where text may be clipped.

## UserAvatar
- **Import:** `./UserAvatar`
- **Description:** Displays a user's profile picture (or initials fallback) with optional email and employee ID — use it wherever a user identity needs to be shown compactly.

## UserCard
- **Import:** `./UserCard`
- **Description:** A popover-style card showing a user's avatar, name, email (with copy), and up to three action buttons — use it for user hover-cards or profile previews.

## VirtualizedList
- **Import:** `./VirtualizedList`
- **Description:** A thin wrapper around react-window's `List` for rendering large item sets efficiently — use it when rendering hundreds of rows without pagination.

## WeekMonthSelector
- **Import:** `./WeekMonthSelector`
- **Description:** Weekly/monthly period selector with arrow navigation. In week mode it displays the Monday–Sunday range (arrows only, no selector). In month mode it displays the active month (arrows + clicking the date opens a month picker with a 4×3 month grid and year navigation).
- **Key props:** `fromDate`, `toDate`, `handleFromChange`, `handleToChange`, `dateFormatter` (same contract as `DatePeriodSelector`), `initialPeriod?: WeekMonthPeriod`.

---

## UserAutoComplete
- **Import:** `./Inputs/UserAutoComplete`
- **Description:** A searchable user-picker backed by a react-query result, with infinite scroll and multi-select support — use it for any "assign to user(s)" field.

---

## PaginationController
- **Import:** `./Pagination/PaginationController`
- **Description:** A MUI TablePagination connected to react-hook-form — use it to control page number and page size in table views.

## SearchBarController
- **Import:** `./Pagination/SearchBarController`
- **Description:** A search text field connected to react-hook-form, built via `buildSearchbar()` — use it as the search input in paginated list views.

---

## BreakdownChart
- **Import:** `./charts/BreakdownChart`
- **Description:** A raw horizontal stacked-bar chart from numeric arrays — use it as the chart primitive inside the `Breakdown` widget or standalone.

## MidCircleChart
- **Import:** `./charts/MidCircleChart`
- **Description:** A raw half-donut SVG chart — use it as the chart primitive inside the `MidCircle` widget or standalone.

## PieChart
- **Import:** `./charts/PieChart`
- **Description:** A raw pie chart — use it as the chart primitive inside the `Pie` widget or standalone.

## ProgressCircleChart
- **Import:** `./charts/ProgressCircleChart`
- **Description:** A raw full-circle progress SVG chart — use it as the chart primitive inside `ProgressCircle` or standalone.

## SingleStackedBarChart
- **Import:** `./charts/SingleStackedBarChart`
- **Description:** A single horizontal stacked bar with optional legend, markers, and percentage labels — use it to visualize response distributions for a single question.

## TreemapChart
- **Import:** `./charts/TreemapChart`
- **Description:** A treemap chart powered by chartjs-chart-treemap — use it to show hierarchical data with area-proportional blocks.

---

## audience/
- **Import:** `./audience`
- **Description:** Complete audience segmentation system for targeting users via condition types (all, individual, segmentation items, or complex expressions).
- **Notes:** Main entry point is `Audience`; also exports `AllCriteriaCard`, `IndividualCriteriaCard`, `SegmentationCriteriaCard`, summary cards, and key types (`SegmentationExpressionPayload`, `SegmentationConditionType`).

## auth/
- **Import:** `./auth`
- **Description:** Authentication UI screens including login form, OTP layout, and instance selector.
- **Notes:** Exports `LoginForm`, `OTPLayout`, `InstanceCard`, `LoginLayout`, `SSOButton`, and `useSelectIntanceDrawer`.

## dynamic-forms/
- **Import:** `./dynamic-forms`
- **Description:** A multi-section dynamic form engine that renders API-driven form sections and handles navigation and submission.
- **Notes:** Uses an imperative ref API (`FormContainerRef`) with `initDynamicForm`, `getDynamicFormProgress`, and `setIsFrozen`. Supports 15+ input types via `DynamicFormInputs` enum.

## files/
- **Import:** `./files`
- **Description:** File attachment management components for upload, display, edit, delete, sort, and download.
- **Notes:** Main component is `Attachments` (has form variant); also exports `FileIcon`, `FileInfo`, `FileItem`, and `ImagePreviewDialog` as lower-level primitives.

## learning/
- **Import:** `./learning`
- **Description:** Course and learning content components for rendering modules and informational text.
- **Notes:** Exports `ModuleAccordion` (collapsible course module) and `TextInformation` (instructional content block).

## peopleExperience/
- **Import:** `./peopleExperience`
- **Description:** Survey analytics and data visualization components for people experience results.
- **Notes:** Exports `Heatmap`, `ScaleQuestionChart`, NPS result components (`npsResults/`), survey result components (`surveyResults/`), `Participation`, `DisplayGroup`, `TableFilterDecorator`, and several utility display components.

## posts/
- **Import:** `./posts`
- **Description:** Social feed components for displaying and creating posts with text, media, and file attachments.
- **Notes:** Exports `Post` (display) and `CreatePost` (form).

## profile/
- **Import:** `./profile`
- **Description:** Profile data display and editing components for showing structured employee profile fields.
- **Notes:** Exports `DataContainer`, `ProfileSingleFieldRow`, `ProfileListFieldRow`, `ProfileListUsersRow`, `useProfileDataDrawer`, and `useProfileUsersDrawer`.

## sign/
- **Import:** `./sign/documents`
- **Description:** Document signing components, including a signing dialog.
- **Notes:** Main export is `SignDialog`; has a form variant (`FormSign`) via `./sign/documents/SignDialog/form`.
