ps-helix 0.1.0

package/README.md

@@ -0,0 +1,286 @@
+# ps-helix
+
+Helix Design System - A comprehensive Angular component library built with Angular 19+ and modern best practices.
+
+## Installation
+
+```bash
+npm install ps-helix
+```
+
+## Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```json
+{
+  "@angular/common": "^19.0.0",
+  "@angular/core": "^19.0.0",
+  "@angular/forms": "^19.0.0",
+  "@ngx-translate/core": "^15.0.0",
+  "rxjs": "^7.8.0"
+}
+```
+
+## Getting Started
+
+### 1. Import Global Styles
+
+In your `styles.css` or `styles.scss` file, import the Helix Design System styles:
+
+```css
+@import 'ps-helix/styles.css';
+```
+
+This will include:
+- CSS Reset
+- Theme variables (light and dark modes)
+- Typography utilities
+- Spacing system
+- Layout utilities
+- Animation utilities
+- Focus styles
+- Responsive breakpoints
+
+### 2. Import Components
+
+All components are standalone and can be imported directly:
+
+```typescript
+import { Component } from '@angular/core';
+import { PshButtonComponent } from 'ps-helix';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [PshButtonComponent],
+  template: `
+    <psh-button
+      [variant]="'primary'"
+      [size]="'medium'">
+      Click me
+    </psh-button>
+  `
+})
+export class AppComponent {}
+```
+
+### 3. Configure Services (Optional)
+
+#### Theme Service
+
+The ThemeService allows you to manage light/dark theme switching:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { ThemeService } from 'ps-helix';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  template: `
+    <button (click)="toggleTheme()">
+      Current theme: {{ themeService.themeName() }}
+    </button>
+  `
+})
+export class AppComponent {
+  themeService = inject(ThemeService);
+
+  toggleTheme() {
+    this.themeService.toggleTheme();
+  }
+}
+```
+
+#### Translation Service
+
+Configure internationalization with the TranslationService:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { TranslationService } from 'ps-helix';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    TranslationService
+  ]
+};
+```
+
+## Available Components
+
+### Form Components
+- `PshButtonComponent` - Versatile button with multiple variants and states
+- `PshInputComponent` - Text input with validation support
+- `PshCheckboxComponent` - Checkbox with customizable states
+- `PshRadioComponent` - Radio button for single selection
+- `PshSelectComponent` - Dropdown select with search
+- `PshSwitchComponent` - Toggle switch component
+
+### Layout Components
+- `PshCardComponent` - Content container with variants
+- `PshModalComponent` - Modal dialog overlay
+- `PshSidebarComponent` - Collapsible sidebar navigation
+- `PshCollapseComponent` - Expandable content section
+- `PshTabsComponent` - Tabbed content organization
+- `PshTabBarComponent` - Bottom tab bar navigation
+
+### Feedback Components
+- `PshAlertComponent` - Alert messages with severity levels
+- `PshToastComponent` - Toast notifications
+- `PshSpinloaderComponent` - Loading spinner
+- `PshProgressbarComponent` - Progress indicator
+- `PshTooltipComponent` - Contextual tooltips
+
+### Data Display Components
+- `PshTableComponent` - Data table with sorting and pagination
+- `PshBadgeComponent` - Status badges and indicators
+- `PshTagComponent` - Removable tags
+- `PshAvatarComponent` - User avatar with fallback
+- `PshPieChartComponent` - Pie chart visualization
+
+### Navigation Components
+- `PshMenuComponent` - Dropdown menu
+- `PshPaginationComponent` - Pagination controls
+- `PshStepperComponent` - Step-by-step wizard
+- `PshDropdownComponent` - Dropdown trigger and content
+
+## Component Usage Examples
+
+### Button
+
+```typescript
+import { PshButtonComponent } from 'ps-helix';
+
+<psh-button
+  [variant]="'primary'"
+  [size]="'medium'"
+  [appearance]="'filled'"
+  [disabled]="false"
+  [loading]="false"
+  (clicked)="handleClick($event)">
+  Submit
+</psh-button>
+```
+
+### Input
+
+```typescript
+import { PshInputComponent } from 'ps-helix';
+import { FormControl } from '@angular/forms';
+
+export class MyComponent {
+  emailControl = new FormControl('');
+}
+
+<psh-input
+  [label]="'Email'"
+  [placeholder]="'Enter your email'"
+  [type]="'email'"
+  [formControl]="emailControl"
+  [required]="true">
+</psh-input>
+```
+
+### Modal
+
+```typescript
+import { PshModalComponent } from 'ps-helix';
+import { signal } from '@angular/core';
+
+export class MyComponent {
+  isOpen = signal(false);
+}
+
+<psh-modal
+  [(open)]="isOpen"
+  [title]="'Confirm Action'"
+  [size]="'medium'">
+  <p>Are you sure you want to proceed?</p>
+  <div class="actions">
+    <psh-button (clicked)="isOpen.set(false)">Cancel</psh-button>
+    <psh-button [variant]="'primary'" (clicked)="confirm()">Confirm</psh-button>
+  </div>
+</psh-modal>
+```
+
+### Toast Notifications
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { ToastService } from 'ps-helix';
+
+export class MyComponent {
+  private toastService = inject(ToastService);
+
+  showSuccess() {
+    this.toastService.success('Operation completed successfully!');
+  }
+
+  showError() {
+    this.toastService.error('An error occurred');
+  }
+
+  showInfo() {
+    this.toastService.info('Information message', { duration: 5000 });
+  }
+}
+```
+
+## Theming
+
+The design system includes built-in support for light and dark themes. Theme switching is handled automatically through the ThemeService.
+
+### Custom Theme Colors
+
+You can customize theme colors by providing an InsurerContextService:
+
+```typescript
+import { InjectionToken } from '@angular/core';
+import { INSURER_CONTEXT_SERVICE } from 'ps-helix';
+
+const myContextService = {
+  primaryColor: () => '#0F02C4',
+  secondaryColor: () => '#7B3AEC'
+};
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: INSURER_CONTEXT_SERVICE,
+      useValue: myContextService
+    }
+  ]
+};
+```
+
+## TypeScript Support
+
+All components are fully typed with TypeScript. Import types as needed:
+
+```typescript
+import {
+  ButtonVariant,
+  ButtonSize,
+  ButtonAppearance
+} from 'ps-helix';
+
+const variant: ButtonVariant = 'primary';
+const size: ButtonSize = 'medium';
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests are welcome on the repository.