@paradox-ui/components

Modern Web Components library built with Lit.

Installation

npm install @paradox-ui/components

Usage

Importing Components

import { Button } from '@paradox-ui/components';
import '@paradox-ui/components/tokens.css';

Using in HTML

<ds-button variant="primary">Click me</ds-button>

Angular Integration

📘 Pełny przewodnik Angular → - szczegółowa dokumentacja z przykładami
🚀 Quick Start → - szybki start z przykładem projektu

Angular ma pełne wsparcie dla Web Components. Oto jak zintegrować bibliotekę z Angularem:

1. Instalacja

npm install @paradox-ui/components

2. Konfiguracja (Angular 15+)

W pliku app.config.ts lub main.ts dodaj schemat CUSTOM_ELEMENTS_SCHEMA:

// app.config.ts (standalone components)
import { ApplicationConfig, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...twoje providery
  ],
  // Dodaj to dla komponentów standalone
};

// Jeśli używasz standalone components, dodaj schema w komponencie:
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})

LUB w pliku app.module.ts (moduły NgModule):

// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Dodaj to
  bootstrap: [AppComponent]
})
export class AppModule { }

3. Import komponentów

W main.ts lub w komponencie, gdzie chcesz użyć Web Components:

// main.ts
import '@paradox-ui/components';
import '@paradox-ui/components/tokens.css';

// ...reszta kodu bootstrapującego

4. Użycie w szablonach

<!-- app.component.html -->
<ds-button variant="primary">Click me</ds-button>

<ds-button 
  variant="secondary" 
  (click)="handleClick()">
  Secondary Button
</ds-button>

5. Obsługa eventów i properties w Angular

// app.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <ds-button 
      [attr.variant]="buttonVariant"
      (click)="handleClick()">
      {{ buttonText }}
    </ds-button>
  `
})
export class AppComponent {
  buttonVariant = 'primary';
  buttonText = 'Click me';

  handleClick() {
    console.log('Button clicked!');
  }
}

6. Style globalne

Zaimportuj style w styles.css lub styles.scss:

/* styles.css */
@import '@paradox-ui/components/tokens.css';

LUB w angular.json:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.css",
              "node_modules/@paradox-ui/components/dist/styles/tokens.css"
            ]
          }
        }
      }
    }
  }
}

7. TypeScript typings (opcjonalne)

Aby uzyskać autouzupełnianie w TypeScript, możesz stworzyć plik deklaracji:

// src/types/web-components.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'ds-button': any;
    'ds-header': any;
    'ds-page': any;
  }
}

React Integration

// React
import '@paradox-ui/components';
import '@paradox-ui/components/tokens.css';

function App() {
  return <ds-button variant="primary">Click me</ds-button>;
}

Vue Integration

<!-- Vue 3 -->
<script setup>
import '@paradox-ui/components';
import '@paradox-ui/components/tokens.css';
</script>

<template>
  <ds-button variant="primary">Click me</ds-button>
</template>

Components

• Button - Customizable button component with multiple variants
• Header - Application header component
• Page - Page layout component

Development

For contributing and development setup, see the repository.

Using Changesets - Changelog Workflow

📘 Pełny przewodnik po changelogach → - szczegółowa dokumentacja z przykładami
🤖 Auto-generowanie z commitów → - automatyczne changesets z historii git (NOWE!)

Ten projekt używa automatycznej kategoryzacji changelogów i wspiera dwa workflows:

Workflow 1: Ręczne tworzenie changesets

Używaj prefiksów conventional commits w opisach zmian:

• feat: - Nowe funkcje (✨ Features)
• fix: - Naprawione błędy (🐛 Bug Fixes)
• docs: - Dokumentacja (📝 Documentation)
• perf: - Wydajność (⚡ Performance)
• refactor: - Refaktoryzacja (♻️ Refactor)
• test: - Testy (✅ Tests)
• chore: - Utrzymanie (🔧 Chore)

Workflow 2: 🚀 Automatyczne z commitów (NOWE!)

# Commituj z conventional commits
git commit -m "feat: dodano komponent Modal"
git commit -m "fix: naprawiono problem z focusem"

# Automatycznie wygeneruj changesets
npm run changeset:from-commits

1. Creating a Changeset

Opcja A: Ręcznie (interaktywnie)

npm run changeset

This will prompt you to:

• Select the type of change (major/minor/patch)
• Describe the changes with appropriate prefix

Opcja B: Automatycznie z commitów 🚀

# Commituj z conventional commits
git commit -m "feat: dodano nowy wariant danger dla Button"
git commit -m "fix: naprawiono styling focus w Input"

# Generuj changesets automatycznie
npm run changeset:from-commits

Example changeset file (.changeset/cool-changes-happen.md):

---
"@paradox-ui/components": minor
---

feat: Dodano nowy wariant danger dla komponentu Button

Example bugfix changeset:

---
"@paradox-ui/components": patch
---

fix: Naprawiono styling stanu focus w komponencie Input

2. Versioning

To bump version and update CHANGELOG:

npm run version

This will:

• Update package.json version
• Update CHANGELOG.md with all changesets automatically categorized
• Delete processed changeset files

3. Example CHANGELOG.md Structure

# @paradox-ui/components

## 0.2.0

### Minor Changes

- [✨ Features] Dodano nowy wariant danger dla komponentu Button
- [✨ Features] Card component obsługuje teraz właściwość hoverable

### Patch Changes

- [🐛 Bug Fixes] Naprawiono styling stanu focus w komponencie Input
- [🐛 Bug Fixes] Poprawiono kontrast stanu disabled dla Button
- [📝 Documentation] Zaktualizowano dokumentację integracji z Angular

## 0.1.0

### Minor Changes

- [✨ Features] Pierwsze wydanie z komponentami Button, Card, i Input

Running the Project

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Build components
npm run build

# Create a changeset
npm run changeset

# Update version and changelog
npm run version

Using the Design System

In your application:

npm install my-design-system

Import tokens globally (once in your app):

// In your main.js or index.html
import 'my-design-system/tokens.css';

Use components:

import 'my-design-system';

// In your HTML
Click me
Content

Best Practices

1. Always create changesets for user-facing changes
2. Use semantic versioning:
   • Major: Breaking changes
   • Minor: New features
   • Patch: Bug fixes
3. Test in Storybook before creating changesets
4. Write descriptive changeset messages for better changelogs
5. Keep components simple and focused on single responsibility

Next Steps

• Add more components following the same pattern
• Configure automatic changelog generation in CI/CD
• Add visual regression testing with Chromatic
• Set up automated releases with GitHub Actions
• Add accessibility testing with @storybook/addon-a11y