npm - @sehgaltech/psui - Versions diffs - 1.0.0 - Mend

@sehgaltech/psui 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,343 @@
+# PSUI
+A scalable and customizable UI library built with Tailwind CSS v4, TypeScript, and React.
+## Features
+- 🎨 **Tailwind CSS v4** - Modern CSS-first configuration with `@theme` blocks
+- 📦 **TypeScript** - Full type safety and excellent developer experience
+- ⚡ **tsup** - Fast and efficient builds with ESM/CJS dual output
+- 📚 **Storybook** - Interactive component documentation and playground
+- 🧪 **Vitest** - Fast unit testing with React Testing Library
+- 🎯 **Tree-shakeable** - Optimized bundle size with side-effect free exports
+- 🎨 **Customizable** - Easy theme customization via CSS variables
+## Installation
+```bash
+npm install psui
+# or
+yarn add psui
+# or
+pnpm add psui
+```
+## Usage
+### Basic Setup
+1. Import the library styles in your application's main CSS file or entry point:
+```tsx
+// In your main CSS file (e.g., index.css or app.css)
+@import 'psui/styles';
+```
+Or in your JavaScript/TypeScript entry file:
+```tsx
+// In your main entry file (e.g., main.tsx or index.tsx)
+import 'psui/styles';
+```
+**Note:** Make sure your build tool supports Tailwind CSS v4. If you're using Vite, install `@tailwindcss/vite` plugin:
+```bash
+npm install -D @tailwindcss/vite
+```
+Then add it to your `vite.config.ts`:
+```ts
+import tailwindcss from '@tailwindcss/vite';
+export default {
+  plugins: [tailwindcss()],
+};
+```
+1. Use components in your React application:
+```tsx
+import { Button } from 'psui';
+function App() {
+  return (
+    <div>
+      <Button variant="primary" size="md">
+        Click me
+      </Button>
+    </div>
+  );
+}
+```
+### Button Component
+The Button component supports multiple variants, sizes, and states:
+```tsx
+import { Button } from 'psui';
+// Variants
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="success">Success</Button>
+<Button variant="danger">Danger</Button>
+<Button variant="warning">Warning</Button>
+<Button variant="ghost">Ghost</Button>
+// Sizes
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+// States
+<Button loading>Loading...</Button>
+<Button disabled>Disabled</Button>
+<Button fullWidth>Full Width</Button>
+```
+## Themes
+PSUI ships with two themes: **Winter** (light) and **Starlight** (dark). Both use OKLCH colors and semantic tokens (base, primary, secondary, accent, neutral, info, success, warning, error).
+### Switching themes
+Set `data-theme` on a root element (e.g. `<html>` or a wrapper):
+```tsx
+// Light (default)
+<html data-theme="winter">
+// Dark
+<html data-theme="starlight">
+```
+You can switch at runtime:
+```tsx
+document.documentElement.setAttribute('data-theme', 'starlight');
+```
+### Theme tokens
+- **Colors**: `base-100`, `base-200`, `base-300`, `base-content`, `primary`, `primary-content`, `secondary`, `secondary-content`, `accent`, `accent-content`, `neutral`, `neutral-content`, `info`, `info-content`, `success`, `success-content`, `warning`, `warning-content`, `error`, `error-content`
+- **Radius**: `--radius-selector`, `--radius-field`, `--radius-box`
+- **Sizes**: `--size-selector`, `--size-field`
+- **Border**: `--border-width`
+### Customization
+Override theme variables for a given theme:
+```css
+[data-theme="winter"] {
+  --theme-primary: oklch(70% 0.12 260);
+}
+```
+## Development
+### Prerequisites
+- Node.js 18+
+- npm, yarn, or pnpm
+### Setup
+```bash
+# Install dependencies
+npm install
+# Start development build in watch mode
+npm run dev
+# Run Storybook
+npm run storybook
+# Run tests
+npm test
+# Type check
+npm run type-check
+# Build library
+npm run build
+```
+### Project Structure
+```
+psui/
+├── src/
+│   ├── components/       # React components
+│   │   ├── Button/
+│   │   └── index.ts
+│   ├── styles/           # Tailwind CSS styles
+│   │   ├── base.css      # Tailwind import
+│   │   └── theme.css     # Theme tokens
+│   ├── types/            # TypeScript types
+│   └── index.ts          # Main entry point
+├── stories/              # Storybook stories
+├── .storybook/           # Storybook config
+└── dist/                 # Build output
+```
+### Adding New Components
+1. Create component directory in `src/components/`:
+```bash
+mkdir src/components/MyComponent
+```
+1. Create component file:
+```tsx
+// src/components/MyComponent/MyComponent.tsx
+import { forwardRef } from 'react';
+import type { ComponentProps } from '../../types';
+export interface MyComponentProps extends ComponentProps<'div'> {
+  // Your props
+}
+export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ className, ...props }, ref) => {
+    return <div ref={ref} className={className} {...props} />;
+  }
+);
+MyComponent.displayName = 'MyComponent';
+```
+1. Export from component index:
+```tsx
+// src/components/MyComponent/index.ts
+export { MyComponent } from './MyComponent';
+export type { MyComponentProps } from './MyComponent';
+```
+1. Export from main components index:
+```tsx
+// src/components/index.ts
+export { MyComponent } from './MyComponent';
+export type { MyComponentProps } from './MyComponent';
+```
+1. Export from main library entry:
+```tsx
+// src/index.ts
+export { MyComponent } from './components';
+export type { MyComponentProps } from './components';
+```
+1. Create Storybook story:
+```tsx
+// stories/MyComponent.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { MyComponent } from '../src/components/MyComponent';
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  tags: ['autodocs'],
+};
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+export const Default: Story = {
+  args: {
+    // Your args
+  },
+};
+```
+## Building and Publishing
+### Build
+```bash
+npm run build
+```
+This generates:
+- `dist/index.js` - CommonJS bundle
+- `dist/index.mjs` - ES Module bundle
+- `dist/index.d.ts` - TypeScript declarations
+- `dist/styles.css` - Compiled CSS
+### Publishing
+1. Update version in `package.json`
+2. Build the library: `npm run build`
+3. Publish to npm: `npm publish`
+## Deployment (Storybook to Vercel)
+Deploy the component documentation (Storybook) to Vercel so others can browse the library online.
+### Prerequisites
+- Project pushed to GitHub, GitLab, or Bitbucket
+- [Vercel](https://vercel.com) account
+### Steps
+1. **Build Storybook locally (optional check)**
+  From the project root:
+   Output is written to the `storybook-static` directory.
+2. **Deploy via Vercel**
+  - In [Vercel](https://vercel.com): **Add New Project** → import your repository.
+  - Configure the project:
+    - **Build Command:** `npm run build-storybook`
+    - **Output Directory:** `storybook-static`
+    - **Install Command:** `npm install` (default)
+  - Deploy. The published URL will serve your Storybook (e.g. Winter/Starlight theme and all stories).
+### Optional: `vercel.json`
+To fix build settings in the repo, add a `vercel.json` in the project root:
+```json
+{
+  "buildCommand": "npm run build-storybook",
+  "outputDirectory": "storybook-static",
+  "installCommand": "npm install"
+}
+```
+Then deploying from Git or the Vercel CLI will use these values automatically.
+## TypeScript Support
+PSUI is written in TypeScript and provides full type definitions. All components export their prop types for use in your applications:
+```tsx
+import type { ButtonProps } from 'psui';
+const MyButton: React.FC<ButtonProps> = (props) => {
+  // Type-safe component
+};
+```
+## Browser Support
+- Safari 16.4+
+- Chrome 111+
+- Firefox 128+
+## License
+MIT
+## Contributing
+Contributions are welcome! Please feel free to submit a Pull Request.