npm package: @inderjotpujara/cosmos-ui
Description: A modern UI component library for Angular applications, built on top of PrimeNG.
Author: Acceldata
Latest version: 0.0.16

# @inderjotpujara/cosmos-ui

A modern UI component library for Angular applications, built on top of PrimeNG.

## Installation

```bash
npm install @inderjotpujara/cosmos-ui
```

All required dependencies (PrimeNG, FontAwesome, etc.) will be automatically installed.

## Usage

Import the components you need in your standalone components:

```typescript
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ButtonComponent, CheckboxComponent } from '@inderjotpujara/cosmos-ui';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    ButtonComponent,
    CheckboxComponent
  ],
  templateUrl: './example.component.html',
  styleUrls: ['./example.component.scss']
})
export class ExampleComponent { }
```

For applications using the Angular bootstrapApplication method:

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { appConfig } from './app.config';

bootstrapApplication(AppComponent, appConfig)
  .catch(err => console.error(err));
```

## Available Components

### Button Component

A versatile button component with extensive customization options.

```html
<lib-button 
  label="Submit" 
  severity="primary" 
  [raised]="true"
  [loading]="isLoading"
  (onClick)="handleClick($event)">
</lib-button>
```

#### Button Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| label | string | undefined | Text to display inside the button |
| severity | 'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'danger' | undefined | Visual style of the button |
| size | 'small' \| 'medium' \| 'large' | 'medium' | Size of the button |
| disabled | boolean | false | When true, the button will be disabled |
| loading | boolean | false | When true, shows a loading state |
| raised | boolean | false | When true, adds a raised effect |
| rounded | boolean | false | When true, adds rounded corners |
| text | boolean | false | When true, renders as a text button |
| outlined | boolean | false | When true, adds an outline style |
| iconPos | 'left' \| 'right' | 'left' | Position of the icon relative to the label |
| ripple | boolean | true | When true, adds a ripple effect on click |

#### Button Events

| Event | Description |
|-------|-------------|
| onClick | Emitted when the button is clicked |
| onFocus | Emitted when the button receives focus |
| onBlur | Emitted when the button loses focus |

### Checkbox Component

A customizable checkbox component that supports template-driven and reactive forms.

```html
<lib-checkbox 
  label="I agree to the terms" 
  [(ngModel)]="agreed"
  [required]="true"
  (onChange)="handleChange($event)">
</lib-checkbox>
```

#### Checkbox Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| label | string | undefined | Label text for the checkbox |
| checked | boolean | false | When true, the checkbox will be checked |
| disabled | boolean | false | When true, the checkbox will be disabled |
| required | boolean | false | When true, the checkbox will be required |
| size | 'small' \| 'medium' \| 'large' | 'medium' | Size of the checkbox |
| labelPosition | 'left' \| 'right' | 'right' | Position of the label relative to the checkbox |
| binary | boolean | false | When true, the checkbox will be used as a binary input |
| readonly | boolean | false | When true, the checkbox will be read-only |

#### Checkbox Events

| Event | Description |
|-------|-------------|
| onChange | Emitted when the checkbox state changes |
| onFocus | Emitted when the checkbox receives focus |
| onBlur | Emitted when the checkbox loses focus |

## Theming

### Setting up the Theme

To use the theming system, you need to import the theme styles in your `angular.json` file:

```json
"styles": [
  "node_modules/@inderjotpujara/cosmos-ui/styles/styles.scss",
  "src/styles.scss"
]
```

Alternatively, you can import the styles in your `styles.scss` file:

```scss
@import '@inderjotpujara/cosmos-ui/styles/styles.scss';
```

### Theme Variables

The library provides theme variables that you can use in your components:

```typescript
import { THEME_VARIABLES, AD_THEME_VARIABLES } from '@inderjotpujara/cosmos-ui';

// Use theme variables
const primaryColor = THEME_VARIABLES.primaryColor;
const accentColor = AD_THEME_VARIABLES.accent;
```

## Development

### Building the Library

To build the library:

```bash
npm run build:lib
```

For production build:

```bash
npm run build:lib:prod
```

### Storybook

This library includes a Storybook instance to showcase and document the components. To run Storybook:

```bash
npm run storybook
```

This will start the Storybook server at http://localhost:6007.

To build the Storybook static site:

```bash
npm run build-storybook
```

This will generate the static Storybook site in the `dist/storybook/ui-lib` directory.

## Project Structure

```
projects/ui-lib/
├── src/
│   └── lib/
│       ├── button/          # Button component
│       ├── checkbox/        # Checkbox component
│       ├── services/        # Shared services
│       ├── styles/          # Global styles and theme variables
│       └── theme.module.ts  # Theme module
├── package.json            # Library package configuration
└── ng-package.json         # Angular library build configuration
```

## Publishing

For detailed instructions on how to publish a new version of the library, see [PUBLISHING.md](./PUBLISHING.md).

### Quick Publishing Steps

#### Method 1: Using npm scripts (Recommended)
```bash
# 1. Update version
cd projects/ui-lib
npm version patch

# 2. Build and publish
cd ../..
npm run build:lib:prod
npm run publish:lib
```

#### Method 2: Manual Steps
```bash
# 1. Update version
cd projects/ui-lib
npm version patch

# 2. Build
cd ../..
npm run build:lib:prod

# 3. Publish
cd dist/ui-lib
npm publish --access public
```

## License

MIT 

## Troubleshooting

### Import Issues

If you are having trouble importing components from the library, try these solutions:

1. **Clear npm cache and reinstall**:
   ```bash
   npm cache clean --force
   npm install @inderjotpujara/cosmos-ui@latest
   ```

2. **Check TypeScript paths**:
   Make sure your `tsconfig.json` has proper path mappings if needed:
   ```json
   {
     "compilerOptions": {
       "paths": {
         "@inderjotpujara/cosmos-ui": ["node_modules/@inderjotpujara/cosmos-ui"]
       }
     }
   }
   ```

3. **Import components and modules correctly**:
   ```typescript
   // Import specific components
   import { Button, Checkbox } from '@inderjotpujara/cosmos-ui';
   
   // Import modules for use in NgModule imports
   import { ButtonModule, CheckboxModule } from '@inderjotpujara/cosmos-ui';
   ```

4. **Make sure Angular compiler options are compatible**:
   In your app's `tsconfig.json`, ensure compatibility with the library:
   ```json
   {
     "compilerOptions": {
       "skipLibCheck": true
     }
   }
   ```