npm package: @prioticket/design-system-web
Description: A comprehensive Web Components library built with **Lit** that provides Material Design components for Prioticket applications. This library is designed to work seamlessly across any frontend framework or in vanilla HTML.
Author: Prioticket
Latest version: 1.7.0

# Prioticket Design System Web

A comprehensive Web Components library built with **Lit** that provides Material Design components for Prioticket applications. This library is designed to work seamlessly across any frontend framework or in vanilla HTML.

## Features

- 🎨 **Material Design 3** - Built on Google's official Material Web components
- 🌈 **Dynamic Theming** - Real-time theme switching without page reload
- 🌐 **Framework Agnostic** - Works with Angular, React, Vue, PHP, or any web technology
- 📦 **Tree Shakable** - Load only the components you need
- 🎯 **TypeScript** - Full type safety and excellent developer experience
- 🔧 **Customizable** - Flexible theming with CSS custom properties
- ⚡ **Performance Optimized** - Individual component bundles for maximum efficiency
- 🎪 **Modern Standards** - ES Modules, Web Components, and HTTP/2 friendly

## Installation

```bash
npm install @prioticket/design-system-web
```

### React projects

We publish official wrappers as `@prioticket/design-system-react`. Install that package alongside the web components when building React apps—see `packages/react/README.md` for setup and usage details.

## Usage Guide

### 1. Quick Start with CDN (Recommended for PHP, Vanilla HTML, etc.)

This is the fastest way to try the components on any plain HTML page while keeping everything tree-shakable.

**Instructions:**
1. Add the Material Symbols font (optional, only needed when you use icons).
2. Include one of the provided theme CSS files.
3. Copy the import map below so the browser can resolve the bare module specifiers used by Lit, Material Web, and tslib.
4. Import the components you need from the CDN.

```html
<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
  <!-- 1. Material Symbols for icons -->
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200">

  <!-- 2. Theme CSS -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/theme-only.css">

  <!-- 3. Import map for the design system and its peer dependencies -->
  <script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.1/index.js",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.1/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.1/lit-html.js",
      "lit-html/": "https://cdn.jsdelivr.net/npm/lit-html@3.3.1/",
      "lit-element": "https://cdn.jsdelivr.net/npm/lit-element@4.2.1/lit-element.js",
      "lit-element/": "https://cdn.jsdelivr.net/npm/lit-element@4.2.1/",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.1.1/reactive-element.js",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.1.1/",
      "@material/web": "https://cdn.jsdelivr.net/npm/@material/web@2.4.0/index.js",
      "@material/web/": "https://cdn.jsdelivr.net/npm/@material/web@2.4.0/",
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.6.2/tslib.es6.js",
      "tslib/": "https://cdn.jsdelivr.net/npm/tslib@2.6.2/"
    }
  }
  </script>
</head>
<body>
  <pd-button>Click Me</pd-button>

  <!-- 4. Import the components you need -->
  <script type="module">
    await import("https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/components/pd-button.es.js");
  </script>
</body>
</html>
```

**Notes:**
- Reuse the same import map for every demo page; add or remove component imports as needed (see `public/component-gallery.html` for a larger example).
- Chromium-based browsers allow this to run directly from `file://` URLs. For Safari/Firefox or when sharing with others, serve the folder over HTTP (for example, `npx http-server public` or `python3 -m http.server`).
- Update the `@prioticket/design-system-web@1.0.7` version string when a new release becomes available.

```html
<!-- Theme CSS options -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/theme-only.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/theme-with-fonts.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/fonts-only.css">
```

**PHP Example:**
```php
<!DOCTYPE html>
<html>
<head>
    <title><?= htmlspecialchars($pageTitle) ?></title>
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/theme-only.css">
    <script type="importmap">{
        "imports": {
            "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.1/index.js",
            "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.1/",
            "@material/web": "https://cdn.jsdelivr.net/npm/@material/web@2.4.0/index.js",
            "@material/web/": "https://cdn.jsdelivr.net/npm/@material/web@2.4.0/",
            "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.6.2/tslib.es6.js",
            "tslib/": "https://cdn.jsdelivr.net/npm/tslib@2.6.2/"
        }
    }</script>
</head>
<body>
    <pd-button variant="filled"><?= htmlspecialchars($buttonText) ?></pd-button>
    <pd-card>
        <h3><?= htmlspecialchars($cardTitle) ?></h3>
        <p><?= htmlspecialchars($cardContent) ?></p>
    </pd-card>

    <script type="module">
        await import("https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/components/pd-button.es.js");
        await import("https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@1.0.7/dist/components/pd-card.es.js");
    </script>
</body>
</html>
```

#### About single-script bundles

The published package focuses on ES modules so that browsers and bundlers can tree-shake unused Material Web dependencies. Producing a one-file UMD/IIFE bundle would dramatically increase payload size, and Vite cannot emit a shared UMD bundle while we expose every component as an entry point. We plan to revisit this once we have a dedicated aggregation build, but for 1.0.7 we recommend sticking with the import-map approach above or a real bundler setup.

### 2. Usage with a Bundler (Framework Integration)

#### Angular

**Step 1: Add CSS to angular.json**

This tells the Angular CLI to include the theme styles in your application's global CSS bundle.

```json
"styles": [
  "src/styles.css",
  "node_modules/@prioticket/design-system-web/dist/theme-only.css"
]
```

**Step 1.5: Add Material Icons to index.html**

Add the Material Icons font to your `src/index.html` file:

```html
<head>
  <!-- Other head content -->
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200">
</head>
```

**Step 2: Import Components and Add Schema**

In your Angular component, import the components to register them and add `CUSTOM_ELEMENTS_SCHEMA`.

```typescript
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

// Import components by their package path
import '@prioticket/design-system-web/components/pd-button';

@Component({
  selector: 'app-example',
  template: `<pd-button>Hello from Angular</pd-button>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ExampleComponent {}
```

#### React / Vue / Other Frameworks

Similar pattern - install via npm, import the CSS file, and import individual components:

```javascript
// Import the theme CSS (exact method depends on your bundler)
import '@prioticket/design-system-web/dist/theme-only.css';

// Import components
import '@prioticket/design-system-web/components/pd-button';

// Use in JSX/template
<pd-button>Hello from React</pd-button>
```

## Available Components

| Component | Description | CDN Import Path |
|-----------|-------------|-----------------|
| pd-button | Material Design buttons | `components/pd-button.es.js` |
| pd-card | Cards for content grouping | `components/pd-card.es.js` |
| pd-checkbox | Checkboxes | `components/pd-checkbox.es.js` |
| pd-chip | Chips for tags/filters | `components/pd-chip.es.js` |
| pd-dialog | Modal dialogs | `components/pd-dialog.es.js` |
| pd-expandable-card | Expandable cards with collapsible content | `components/pd-expandable-card.es.js` |
| pd-fab | Floating action buttons | `components/pd-fab.es.js` |
| pd-icon | Material Design icons | `components/pd-icon.es.js` |
| pd-icon-button | Icon buttons | `components/pd-icon-button.es.js` |
| pd-list | Lists with items | `components/pd-list.es.js` |
| pd-menu | Dropdown menus | `components/pd-menu.es.js` |
| pd-menu-item | Individual menu items | `components/pd-menu-item.es.js` |
| pd-progress | Progress indicators | `components/pd-progress.es.js` |
| pd-radio | Radio buttons | `components/pd-radio.es.js` |
| pd-segmented-button | Segmented button controls | `components/pd-segmented-button.es.js` |
| pd-segmented-stepper | Segmented stepper navigation | `components/pd-segmented-stepper.es.js` |
| pd-select | Select dropdowns | `components/pd-select.es.js` |
| pd-slider | Range sliders | `components/pd-slider.es.js` |
| pd-stepper | Step indicators | `components/pd-stepper.es.js` |
| pd-switch | Toggle switches | `components/pd-switch.es.js` |
| pd-tabs | Tab navigation | `components/pd-tabs.es.js` |
| pd-text-field | Text input fields | `components/pd-text-field.es.js` |

## Dynamic Theming

The design system supports real-time theme switching without page reload. Apply custom themes dynamically to match your brand or user preferences.

### Basic Usage

```javascript
// Import the theming system
import { initialize } from '@prioticket/design-system-web/theming';

// Apply a custom theme
await initialize({
  theme: {
    colorPrimary: '#ff6600',
    colorOnPrimary: '#ffffff',
    colorSurface: '#fff8f5',
    shapeCornerSmall: '8px'
  }
});
```

### CDN Usage

```html
<script type="module">
  import { initialize } from 'https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@latest/dist/theming.es.js';
  
  // Apply orange theme
  await initialize({
    theme: {
      colorPrimary: '#ff6600',
      colorPrimaryContainer: '#fff3e8',
      shapeCornerMedium: '12px'
    }
  });
</script>
```

### Supported Theme Tokens

- **Colors**: `colorPrimary`, `colorOnPrimary`, `colorPrimaryContainer`, `colorSecondary`, `colorSurface`, `colorOnSurface`, `colorBackground`, `colorError`
- **Shapes**: `shapeCornerSmall`, `shapeCornerMedium`, `shapeCornerLarge`

### Framework Examples

**React:**
```jsx
useEffect(() => {
  initialize({ 
    theme: { colorPrimary: '#4caf50' } 
  });
}, []);
```

**Angular:**
```typescript
ngOnInit() {
  initialize({ 
    theme: { colorPrimary: '#2196f3' } 
  });
}
```

### Live Demo

Run `npm run dev` and visit `/demo-theming.html` to see real-time theme switching in action.

## Customizing Fonts

The design system is built to work with any font stack. The theme CSS uses CSS custom properties:

```css
/* Override Prioticket fonts with your own */
:root {
  --md-sys-typescale-body-large-font: "Your Font", Arial, sans-serif;
  --md-sys-typescale-title-medium-font: "Your Font", Arial, sans-serif;
  --md-sys-typescale-headline-small-font: "Your Font", Arial, sans-serif;
}
```

## CSS Architecture

- **theme-only.css** (14KB) - All component styles without fonts
- **fonts-only.css** (1.3KB) - Just Prioticket font declarations  
- **theme-with-fonts.css** (15.7KB) - Complete theme including fonts
- **fonts/** - Font files (~232KB total)

Choose `theme-only.css` to use your existing fonts, or `theme-with-fonts.css` for the complete Prioticket experience.

## Performance Best Practices

1. **Load only what you need** - Import individual components via CDN
2. **Use theme-only.css** - If you already have fonts, skip the font files
3. **Leverage HTTP/2** - Multiple small files load efficiently on modern servers
4. **CDN for Lit** - Load the Lit dependency from a fast CDN
5. **Conditional loading** - In server-side apps, only load components used on each page

## Browser Support

- Chrome 84+
- Firefox 90+
- Safari 14+
- Edge 84+

## Development

```bash
# Install dependencies
yarn install

# Start development server
yarn dev

# Build the library
yarn build

# Run Storybook
yarn storybook
```

## Contributing

This project is open for internal contributions. See our documentation:

- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Complete developer guide for adding components and features
- **[RELEASE-SETUP.md](RELEASE-SETUP.md)** - CI/CD setup and release workflow

### Quick Start for Contributors

1. Clone the repository
2. Install dependencies: `yarn install`
3. Create a feature branch from `development`
4. Make your changes and test in Storybook: `yarn storybook`
5. Write tests: `yarn test`
6. Commit using [Conventional Commits](https://www.conventionalcommits.org/): `git commit -m "feat: Add new feature"`
7. Push and create a Merge Request to `development`

Our automated CI/CD will handle versioning and publishing based on your commit messages.

## Source Code

The source code for this library is proprietary and maintained in a private repository at Prioticket.

## Support

For questions or bug reports, please contact the Prioticket development team internally.