struct-ui-components/README.md

A collection of reusable, customizable React components built with TypeScript, Tailwind CSS, and Storybook. Designed for modern UI development with flexibility and scalability.

# Struct UI Components

## Description

A collection of reusable, customizable React components built with TypeScript, Tailwind CSS, and Storybook. Designed for modern UI development with flexibility and scalability, this library provides a set of essential UI elements and hooks to accelerate the development of React applications. The components are styled with Tailwind CSS, offering a consistent and customizable design system. Storybook integration allows for easy component showcasing and testing.

## File Structure

```
/src
├── components/          # Reusable React components
│   ├── core/             # Core components (Button, Card, etc.)
│   ├── form/             # Form-related components
│   ├── table/            # Table components
│   └── utils/            # Utility components
├── hooks/               # Custom React hooks
├── utils/               # Utility functions
├── assets/              # Assets (CSS, fonts, images)
└── index.ts             # Entry point for the library
```

## Core Components

*   **Accordion:** A vertically collapsing panel that displays large amounts of content in an organized way. It allows users to expand and collapse sections of content, making it ideal for FAQs, documentation, and other content-heavy pages.
*   **Alert:** Displays important messages to the user, such as success, error, warning, or informational messages. It can be customized with different styles and icons.
*   **AlertBox:** A styled container for alerts, providing a consistent look and feel.
*   **Avatar:** A visual representation of a user, typically displaying a user's initials or profile picture.
*   **Badge:** A small visual indicator, often used to display a count or status.
*   **Breadcrumbs:** A navigation aid that shows the user's current location within the application.
*   **Button:** An interactive element that triggers an action, such as submitting a form or navigating to a new page.
*   **ButtonGroup:** A container for grouping buttons together, providing a consistent layout and spacing.
*   **Card:** A flexible container for displaying content, such as articles, products, or user profiles.
*   **Checkbox:** Allows the user to select one or more options from a list.
*   **Dialog:** A modal window that appears on top of the main content, used for displaying important information or prompting the user for input.
*   **Dropdown:** A toggleable menu that allows the user to choose one value from a predefined list.
*   **Image:** Displays images with optional styling and lazy loading.
*   **Input:** Allows the user to enter text, such as usernames, passwords, or search queries.
*   **InputGroup:** A container for grouping inputs together, providing a consistent layout and spacing.
*   **Label:** A text label for form elements, providing context and accessibility.
*   **List:** Displays a list of items, such as navigation links or product listings.
*   **Loader:** Indicates that content is loading, providing feedback to the user.
*   **Modal:** A dialog box/popup window that is displayed on top of the current page, used for displaying important information or prompting the user for input.
*   **Notification:** Displays a brief message to the user, typically used for non-critical updates or alerts.
*   **Pagination:** Allows the user to navigate through multiple pages of content, such as search results or product listings.
*   **Progressbar:** Visually represents the progress of a task, such as uploading a file or completing a form.
*   **Radio:** Allows the user to select one option from a list.
*   **Table:** Displays data in a tabular format, with features such as sorting, filtering, and pagination.
*   **Tabs:** Allows the user to switch between different views, such as different sections of a profile or different categories of products.
*   **Textarea:** Allows the user to enter multi-line text, such as comments or descriptions.
*   **Tooltip:** Displays information when the user hovers over an element, providing additional context or guidance.
*   **Widget:** A small application that can be installed and run within a web page, providing specific functionality or information.

## Hooks

*   **useArray:** Provides utility functions for working with arrays, such as adding, removing, and updating elements.
*   **useAsync:** Handles asynchronous operations, such as fetching data from an API or performing a long-running task.
*   **useClickOutside:** Detects clicks outside of a specified element, allowing you to close a dropdown or modal when the user clicks away.
*   **useCookie:** Manages cookies, allowing you to store and retrieve data in the user's browser.
*   **useCopyToClipboard:** Copies text to the clipboard, providing a convenient way for users to share information.
*   **useDarkMode:** Toggles dark mode, allowing users to switch between light and dark themes.
*   **useDebounce:** Debounces a function, preventing it from being called too frequently.
*   **useDebugInformation:** Provides debug information, such as the component's render count and props.
*   **useDeepCompareEffect:** A useEffect hook that uses deep comparison, ensuring that the effect only runs when the dependencies have actually changed.
*   **useEffectOnce:** A useEffect hook that runs only once, similar to componentDidMount in class components.
*   **useEventListener:** Adds an event listener to an element, allowing you to respond to user interactions or other events.
*   **useFetch:** Fetches data from an API, providing a simple and convenient way to retrieve data from a remote server.
*   **useGeolocation:** Gets the user's geolocation, allowing you to display location-based content or provide location-aware features.
*   **useHover:** Detects when the user hovers over an element, allowing you to display tooltips or other hover-related effects.
*   **useLongPress:** Detects long presses on an element, allowing you to trigger a different action when the user presses and holds an element.
*   **useMediaQuery:** Detects media query changes, allowing you to adapt your UI to different screen sizes or devices.
*   **useOnlineStatus:** Detects the user's online status, allowing you to display a message when the user is offline or disable certain features.
*   **useOnScreen:** Detects when an element is on screen, allowing you to lazy load images or trigger animations when an element becomes visible.
*   **usePrevious:** Returns the previous value of a variable, allowing you to compare the current value to the previous value.
*   **useRenderCount:** Returns the number of times a component has rendered, useful for debugging performance issues.
*   **useScript:** Loads a script, allowing you to dynamically load external scripts or libraries.
*   **useStateWithHistory:** Manages state with history, allowing you to implement undo/redo functionality.
*   **useStateWithValidation:** Manages state with validation, ensuring that the state is always valid.
*   **useStorage:** Manages local storage, allowing you to store and retrieve data in the user's browser.
*   **useTimeout:** Sets a timeout, allowing you to execute a function after a specified delay.
*   **useToggle:** Toggles a boolean value, providing a simple way to switch between two states.
*   **useTranslation:** Handles translations, allowing you to create multilingual applications.
*   **useUpdateEffect:** A useEffect hook that only runs on updates, skipping the initial render.
*   **useWindowSize:** Gets the window size, allowing you to adapt your UI to different screen sizes.

## Utilities

*   **dates.ts:** Date-related utility functions, such as formatting dates and calculating time differences.
*   **index.ts:** General utility functions, such as string manipulation, data formatting, and other common tasks.

## Dependencies

*   **@fortawesome/fontawesome-svg-core:** Font Awesome SVG core.
*   **@fortawesome/free-brands-svg-icons:** Font Awesome brand icons.
*   **@fortawesome/free-regular-svg-icons:** Font Awesome regular icons.
*   **@fortawesome/free-solid-svg-icons:** Font Awesome solid icons.
*   **@fortawesome/react-fontawesome:** Font Awesome React component.
*   **@react-hook/window-size:** React hook for getting the window size.
*   **@tanstack/react-table:** Headless UI for building powerful tables & datagrids for React.
*   **classnames:** A simple JavaScript utility for conditionally joining classNames together.
*   **copy-to-clipboard:** Copy text to the clipboard.
*   **js-cookie:** A simple, lightweight JavaScript API for handling browser cookies.
*   **react:** A JavaScript library for building user interfaces.
*   **react-charts:** Simple, declarative React charts.
*   **react-dom:** Provides DOM-specific methods that are useful for managing a component in the browser.
*   **react-router:** A standard library for routing in React.
*   **react-router-dom:** A DOM bindings for React Router.

## Installation

```bash
yarn install
```

## Usage

```jsx
import { Button } from 'struct-ui-components';

function App() {
  return (
    <Button onClick={() => alert('Clicked!')}>Click me</Button>
  );
}
```

## Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

## License

[MIT](LICENSE)