@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

npm install @physiq/ui

Peer Dependencies

Make sure you have the following peer dependencies installed in your project:

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:

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:

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

import { Input } from "@physiq/ui";

Components

Input

A flexible input component with label and tooltip support.

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

<Input
  inputId="username"
  label="Username"
  placeholder="Enter username"
  type="text"
  value={username}
  onChange={handleUsernameChange}
/>

Number Input with Tooltip

<Input
  inputId="age"
  label="Age"
  placeholder="Enter your age"
  type="number"
  value={age}
  onChange={handleAgeChange}
  tooltip="Must be 18 or older"
/>

Styled Input

<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

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Build the library
npm run build

Build

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:

   # 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:

   npm run build

3. Publish to npm:

   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

# 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:

# 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 - UI library
• TypeScript - Type safety
• Radix UI - Accessible primitives
• Tailwind CSS - Utility-first CSS
• Lucide React - Icon library
• Vite - Build tool

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.