react-animated-select 0.2.9 → 0.3.6

package/README.md

@@ -2,30 +2,28 @@
 
 A lightweight, high-performance, and fully customizable Select component for React. Featuring smooth CSS animations, accessible keyboard navigation, and flexible option rendering.
 
+**Try it out:**
+
+[![Demo](https://img.shields.io/badge/demo-live_preview-brightgreen?style=for-the-badge&logo=vercel)](https://l1nway.github.io/react-animated-select/)
+
 ## Features
 
 -  **Smooth Animations**
-
 Powered by `react-transition-group` with height-expanding dropdowns and sliding side-elements.
 
 -  **Accessible**
-
 Full keyboard support (Arrow keys, Enter, Space, Escape, Tab) and ARIA attributes built-in.
 
 -  **Flexible Data**
-
-Supports simple arrays, objects, or declarative JSX children (`<Option />`).
+Supports simple arrays, objects, or declarative JSX children (`<Option />`). **Smart deep parsing** extracts labels from any available object key.
 
 -  **Smart Auto-Positioning**
-
 Recalculates dropdown position using `ResizeObserver`.
 
 -  **Zero-Config Styles**
-
 The minimum styles required for the select to work are built into the project, but you can add your own on top of the basic ones.
 
 -  **Search & Clear**
-
 Built-in “Clear” button and intelligent state handling (loading, error, empty, disabled).
 
 ## Installation
@@ -81,10 +79,10 @@ function App() {
 | `disabled` | `boolean` | `false` | Disables the entire component. |
 | `loading` | `boolean` | `false` | Shows a loading animation and disables interaction. |
 | `error` | `boolean` | `false` | Shows the error state and `errorText`. |
-| `style` | `object` | `{}` | Inline styles for the root container. |,
-| `className` | `string` | '' | Additional CSS class for the root container .rac-select. |,
+| `style` | `object` | `{}` | Inline styles for the root container. |
+| `className` | `string` | '' | Additional CSS class for the root container .rac-select. |
 | `ArrowIcon` | `ElementType \ string \ JSX` | Default icon | Custom arrow icon. Accepts a component, image path, or JSX. |
-| `ClearIcon` | `ElementType \ string \ JSX` | Default icon | Custom clear icon. Accepts a component, image path, or JSX. |,
+| `ClearIcon` | `ElementType \ string \ JSX` | Default icon | Custom clear icon. Accepts a component, image path, or JSX. |
 
 ---
 
@@ -101,12 +99,20 @@ function App() {
 
 ### Behavioral Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `visibility` | `boolean` | `false` | Manually controls the visibility of the list (used with `ownBehavior`). |
-| `ownBehavior` | `boolean` | `false` | If `true`, the component stops managing its own open/close state and relies on the `visibility` prop. |
-| `alwaysOpen` | `boolean` | `false` | Keeps the list permanently visible. Primarily used for debugging or specific UI layouts. |
-| `unmount` | `boolean` | `true` | When `true`, the list is removed from the DOM when closed. When `false`, it stays invisible in the DOM. |
+| Prop            | Type       | Default    | Description |
+| --------------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------- |
+| `visibility`    | `boolean`  | `false`    | Manually controls the visibility of the list (used with `ownBehavior`). |
+| `ownBehavior`   | `boolean`  | `false`    | If `true`, the component stops managing its own open/close state and relies on the `visibility` prop. |
+| `alwaysOpen`    | `boolean`  | `false`    | Keeps the list permanently visible. Primarily used for debugging or specific UI layouts. |
+| `unmount`       | `boolean`  | `true`     | When `true`, the list is removed from the DOM when closed. When `false`, it stays invisible in the DOM. |
+| `hasMore`       | `boolean`  | `false`    | Indicates whether more options are available for loading (used for infinite loading). |
+| `loadMore`      | `function` | `() => {}` | Callback triggered when more options need to be loaded. |
+| `loadMoreText`  | `string`   | `'Loading'`  | Text displayed inside the options list during loading. |
+| `loadOffset`    | `number`   | `100`      | Distance (in pixels) from the bottom of the list that triggers `loadMore`. |
+| `loadAhead`     | `number`   | `3`        | Number of remaining options before the end at which loading is triggered during keyboard navigation. |
+| `loadButton`     | `boolean` | `false`       | Enables a manual “Load more” button instead of automatic loading. |
+| `loadButtonText` | `string`  | `'Load more'` | Text displayed on the load button.                                |
+| `childrenFirst` | `boolean`  | `false`    | Determines priority of JSX `<Option />` children over options passed via props. |
 
 ---
 
@@ -125,12 +131,21 @@ function App() {
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `id` | `string` | Optional unique ID (generated automatically if not provided). value may be used instead of id (lower priority)|
+| `id` | `string` | Optional unique ID (generated automatically if not provided). value may be used instead of id (lower priority). |
 | `disabled` | `boolean` | If true, this option cannot be selected or highlighted. |
 | `className` | `string` | Custom class for individual option styling. |
 
 ---
 
+### `<OptGroup />`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Optional unique ID (generated automatically if not provided). value may be used instead of id (lower priority). |
+| `name` | `string` | OptGroup title. label may be used instead of id (lower priority). |
+
+---
+
 ## Keyboard Support
 
 | Key | Action |
@@ -202,8 +217,17 @@ The component uses CSS variables for deep styling. These are based on system col
 | `--rac-true-option-color` | `color-mix(...)` | Text color for "Boolean True" items. |
 | `--rac-false-option-color` | `color-mix(...)` | Text color for "Boolean False" items. |
 | `--rac-option-padding` | `0.5em` | Internal padding for each option item. |
+| `--rac-option-min-height` | `1em` | Minimum option height. |
 | `--rac-invalid-option-color` | `color-mix(...)` | Text color for invalid options. |
 | `--rac-warning-option-color` | `color-mix(...)` | Text color for warning/caution options. |
+| **Group Headers** | | |
+| `--rac-group-header-font-size` | `1.25em` | Font size of the group header label. |
+| `--rac-group-header-font-weight` | `bold` | Font weight of the group header text. |
+| `--rac-group-header-min-height` | `1em` | Minimum height of the group header item. |
+| `--rac-group-header-padding` | `0.5em` | Internal padding for the group header. |
+| `--rac-group-arrow-height` | `1em` | Height of the group expand/collapse arrow icon. |
+| `--rac-group-arrow-width` | `1em` | Width of the group expand/collapse arrow icon. |
+| `--rac-group-arrow-padding` | `1px 0 2px` | Padding applied to the group arrow icon. |
 
 ---
 
@@ -241,23 +265,23 @@ The select and its options react to internal states by applying the following cl
 - `.rac-invalid-option`: Applied to items that are not valid data types (e.g., functions).
 - `.rac-true-option`: Specialized styling when the option's raw value is exactly `true`.
 - `.rac-false-option`: Specialized styling when the option's raw value is exactly `false`.
+#### Group Header States (applied to group-related elements)
+- `.rac-group-header`: Base class for the group header container.
+- `.rac-group-title-text`: Applied to the text/label inside the group header.
+- `.rac-group-arrow-wrapper`: Wrapper class for the group expand/collapse arrow icon.
 
 #### Trigger States
 - `.rac-select-arrow-wrapper.--open`: Applied to the arrow icon when the dropdown is expanded.
 
 ## Change log
-### 0.2.7
-#### **New Features**
-- **Custom Icons Support:** Added `ArrowIcon` and `ClearIcon` props. Users can now pass their own SVG components, image paths, or JSX elements to customize the interface.
-- **Ref Forwarding:** Implemented access to the internal ref. This enables manual focus management and integration with third-party libraries.
-- **Enhanced Styling:** Added `className` and `style` prop to the root `.rac-select` container for easier layout integration and style overrides.
-- **Animated Title Transitions:** Introduced a smooth "fade-and-slide" animation for the `title` element when the value changes.
-
-#### **Architecture & CSS**
-- **CSS Variable Injection:** Refactored animation parameters into CSS custom properties (`--rac-title-anim-shift`, `--rac-title-anim-entry-ease`
-
-#### **Bug Fixes**
-- **Opacity Animation:** Resolved an issue where the optional opacity transition for the dropdown list was not triggering correctly during the enter/exit phases.
+### 0.3.5
+### New Features
+- **Hierarchical Grouping Engine**: Added full support for nested options using a flat-array normalization technique. This allows for clear visual separation of categories with zero performance overhead.
+-   **Smart "SlideDown" Groups**: Implemented collapsible group headers with smooth animations.
+    -   _Self-Aware UI:_ Group arrows now automatically hide if a group contains no items, providing a cleaner look for empty categories.
+-   **Flexible Data Normalization**: The logic now seamlessly handles `Arrays`, `Objects` (maps), and `JSX` children simultaneously.
+### Bug Fixes
+-   **Dynamic Load Button Toggle**: Fixed a critical bug where the "Load More" button's visibility wouldn't update dynamically. The component now correctly reacts to real-time changes in the `loadButton` and `hasMore` props.
 
 ## License
 

package/demo/README.md

@@ -0,0 +1,16 @@
+# React + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.

package/demo/eslint.config.js

@@ -0,0 +1,29 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import {defineConfig, globalIgnores} from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{js,jsx}'],
+    extends: [
+      js.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: {jsx: true},
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
+    },
+  },
+])

package/demo/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>