npm package: @physiq/ui
Description: A modern React UI component library built with TypeScript, Tailwind CSS, and Radix UI primitives. Designed for building beautiful and accessible user interfaces with ease.
Latest version: 1.8.1

# @physiq/ui

A modern React UI component library built with TypeScript, Tailwind CSS, and Radix UI primitives. Designed for building beautiful and accessible user interfaces with ease.

## Features

- 🚀 **TypeScript First** - Built with TypeScript for better development experience
- 🎨 **Tailwind CSS** - Utility-first CSS framework for rapid styling
- ♿ **Accessible** - Built on top of Radix UI primitives for accessibility
- 📦 **Tree Shakeable** - Import only what you need
- 🔧 **Customizable** - Flexible styling with CSS classes
- 📱 **Responsive** - Mobile-first design approach

## Installation

```bash
npm install @physiq/ui
```

### Peer Dependencies

Make sure you have the following peer dependencies installed in your project:

```bash
npm install react react-dom lucide-react tailwindcss
```

### Tailwind CSS Setup

This library requires Tailwind CSS to be configured in your project. **Important:** You must include the source files in your Tailwind content configuration for styles to work properly.

#### Option 1: Scan Source Files (Recommended)

Add the package source files to your `tailwind.config.js`:

```js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@physiq/ui/src/**/*.{js,ts,jsx,tsx}", // Scan source files
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

#### Option 2: Use Safelist

Alternatively, you can import the safelist from the package:

```js
const physiqSafelist = require("@physiq/ui/safelist");

module.exports = {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  safelist: physiqSafelist, // Include all component classes
  theme: {
    extend: {},
  },
  plugins: [],
};
```

**Note:** After configuring Tailwind, restart your development server for changes to take effect.

## Usage

### Basic Import

```tsx
import { Input } from "@physiq/ui";
```

### Components

#### Input

A flexible input component with label and tooltip support.

```tsx
import { Input } from "@physiq/ui";

function MyForm() {
  const [value, setValue] = useState("");

  const handleChange = ({ key, value }) => {
    setValue(value);
  };

  return (
    <Input
      inputId="email"
      label="Email Address"
      placeholder="Enter your email"
      type="email"
      value={value}
      onChange={handleChange}
      tooltip="We'll never share your email with anyone else"
    />
  );
}
```

##### Props

| Prop          | Type                                                       | Required | Description                                      |
| ------------- | ---------------------------------------------------------- | -------- | ------------------------------------------------ |
| `inputId`     | `string`                                                   | ✅       | Unique identifier for the input                  |
| `value`       | `string \| number`                                         | ✅       | Input value                                      |
| `onChange`    | `(data: { key: string; value: string \| number }) => void` | ✅       | Change handler                                   |
| `placeholder` | `string`                                                   | ✅       | Placeholder text                                 |
| `type`        | `string`                                                   | ✅       | Input type (text, email, password, number, etc.) |
| `label`       | `string`                                                   | ❌       | Label text                                       |
| `labelStyles` | `string`                                                   | ❌       | CSS classes for label styling                    |
| `inputStyles` | `string`                                                   | ❌       | CSS classes for input styling                    |
| `tooltip`     | `string`                                                   | ❌       | Tooltip text with info icon                      |

##### Examples

**Basic Text Input**

```tsx
<Input
  inputId="username"
  label="Username"
  placeholder="Enter username"
  type="text"
  value={username}
  onChange={handleUsernameChange}
/>
```

**Number Input with Tooltip**

```tsx
<Input
  inputId="age"
  label="Age"
  placeholder="Enter your age"
  type="number"
  value={age}
  onChange={handleAgeChange}
  tooltip="Must be 18 or older"
/>
```

**Styled Input**

```tsx
<Input
  inputId="password"
  label="Password"
  placeholder="Enter password"
  type="password"
  value={password}
  onChange={handlePasswordChange}
  labelStyles="text-lg font-semibold"
  inputStyles="border-2 border-blue-500"
/>
```

## Styling

This library is designed to work with Tailwind CSS. You can customize the appearance of components by passing CSS classes through the styling props:

- `labelStyles` - For customizing label appearance
- `inputStyles` - For customizing input field appearance

## Development

### Prerequisites

- Node.js (16 or higher)
- npm or yarn

### Setup

```bash
# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Build the library
npm run build
```

### Build

```bash
npm run build
```

This will generate:

- `dist/index.js` - CommonJS build
- `dist/index.esm.js` - ES modules build
- `dist/index.d.ts` - TypeScript declarations

### Publishing

To publish a new version of the package to npm:

1. **Update the version number** using npm's version commands:

   ```bash
   # For patch releases (bug fixes)
   npm version patch

   # For minor releases (new features)
   npm version minor

   # For major releases (breaking changes)
   npm version major
   ```

2. **Build the package**:

   ```bash
   npm run build
   ```

3. **Publish to npm**:
   ```bash
   npm publish
   ```

The `npm version` command will automatically update the version number in `package.json` and create a git tag. Make sure you're logged into npm (`npm login`) before publishing.

### Storybook

This project includes Storybook for component documentation and testing.

#### Local Development

```bash
# Start Storybook locally
npm run storybook
```

#### GitHub Pages Deployment

Storybook is automatically deployed to GitHub Pages when you push to the `master` branch. The deployment is handled by a GitHub Actions workflow.

**Live Storybook**: `https://johngaynor.github.io/physiq-ui/`

#### Manual Deployment

You can also build Storybook manually:

```bash
# Build Storybook for production
npm run build-storybook

# This creates a `storybook-static` folder with the built Storybook
```

#### Publishing Checklist

- [ ] All tests pass
- [ ] Code is built successfully (`npm run build`)
- [ ] Version number is updated (`npm version patch/minor/major`)
- [ ] Changes are documented
- [ ] You're logged into npm (`npm login`)
- [ ] Ready to publish (`npm publish`)

## Built With

- [React](https://reactjs.org/) - UI library
- [TypeScript](https://www.typescriptlang.org/) - Type safety
- [Radix UI](https://www.radix-ui.com/) - Accessible primitives
- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
- [Lucide React](https://lucide.dev/) - Icon library
- [Vite](https://vitejs.dev/) - Build tool

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

[MIT](LICENSE)

## Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.