@inderjotpujara/cosmos-ui

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

Installation

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:

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:

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.

<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.

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

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

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

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

Theme Variables

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

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:

npm run build:lib

For production build:

npm run build:lib:prod

Storybook

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

npm run storybook

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

To build the Storybook static site:

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.

Quick Publishing Steps

Method 1: Using npm scripts (Recommended)

# 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

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

   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:

   {
     "compilerOptions": {
       "paths": {
         "@inderjotpujara/cosmos-ui": ["node_modules/@inderjotpujara/cosmos-ui"]
       }
     }
   }

3. Import components and modules correctly:

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

   {
     "compilerOptions": {
       "skipLibCheck": true
     }
   }