@krrli/cm-designsystem 1.1.0 → 1.19.8

package/README.md

@@ -1,2 +1,422 @@
-# cm-designsystem
-Design System
+# CM Design System
+
+A modern React component library built with TypeScript, Tailwind CSS, and Storybook.
+
+## Table of Contents
+
+- [Usage in Your Project](#usage-in-your-project)
+- [Technical Stack](#technical-stack)
+- [Development](#development)
+  - [Quick Start Development](#quick-start-development)
+  - [Quality Checks](#quality-checks)
+  - [Code Style](#code-style)
+  - [TypeScript Guidelines](#typescript-guidelines)
+  - [Project Structure](#project-structure)
+- [Icon Generation](#icon-generation)
+- [Visual Testing](#visual-testing)
+- [Contributing](#contributing)
+- [Continuous Integration](#continuous-integration)
+- [EditorConfig & VS Code Settings](#editorconfig--vs-code-settings)
+
+## Usage in Your Project
+
+To use the components and styles in your project:
+
+1. Install the package:
+
+```bash
+npm i @krrli/cm-designsystem
+```
+
+2. Import the bundled CSS in your app entry (e.g., `main.tsx` or `App.tsx`):
+
+```js
+import "cm-designsystem/dist/cm-designsystem.css";
+```
+
+3. Import and use components as needed:
+
+```js
+import { Button } from "cm-designsystem";
+
+function App() {
+  return (
+    <Button label="Click me" intent="primary" size="md" onClick={() => {}} />
+  );
+}
+```
+
+---
+
+## Technical Stack
+
+- React 19 with TypeScript
+- Vite for fast development and building
+- Tailwind CSS v4 for styling
+- Storybook for component documentation
+- Vitest for unit testing
+- Playwright for visual regression testing
+- Radix UI Primitives for accessible component primitives
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react) for Fast Refresh
+
+---
+
+## Development
+
+### Quick Start Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook development server
+npm run storybook
+```
+
+Storybook will be available at [http://localhost:6006](http://localhost:6006)
+
+📚 View the deployed Storybook: [https://ost-cas-fea-25-26.github.io/cm-designsystem/](https://ost-cas-fea-25-26.github.io/cm-designsystem/?path=/docs/branding-assets--docs)
+
+### Quality Checks
+
+Run all quality checks before committing:
+
+```bash
+npm run preflight        # Runs format, lint, type-check, test, and build
+```
+
+Individual commands:
+
+```bash
+# Formatting
+npm run format           # Auto-format all files with Prettier
+npm run format:check     # Check formatting without making changes
+
+# Linting
+npm run lint             # Check for linting errors
+npm run lint:fix         # Auto-fix linting errors where possible
+
+# Type Checking
+npx tsc -b --noEmit      # Run TypeScript type checking
+
+# Testing
+npm test                 # Run unit tests with Vitest
+
+# Building
+npm run build            # Build the project
+npm run build-storybook  # Build Storybook for production
+```
+
+### Code Style
+
+We enforce consistent code style using automated tools:
+
+Prettier Configuration:
+
+- Uses double quotes
+- 2-space indentation
+- Semicolons required
+- Line width: 80 characters
+- Includes Tailwind CSS class sorting plugin
+
+ESLint Configuration:
+
+- TypeScript ESLint rules
+- React and React Hooks best practices
+- JSX Accessibility (a11y) rules
+- Import sorting and organization
+- Storybook rules
+- Prettier integration (no conflicts)
+
+### TypeScript Guidelines
+
+We follow a consistent pattern for component type definitions:
+
+Standard Component Pattern:
+
+```tsx
+import { tv, type VariantProps } from "tailwind-variants";
+
+// 1. Define styles with tailwind-variants
+const buttonStyles = tv({
+  variants: {
+    intent: {
+      primary: ["bg-slate-600"],
+      secondary: ["bg-violet-600"],
+    },
+    size: {
+      md: ["pt-3", "pb-3"],
+      lg: ["pt-4", "pb-4"],
+    },
+  },
+});
+
+// 2. Extract variant types from styles
+type ButtonVariants = VariantProps<typeof buttonStyles>;
+
+// 3. Define specific union types for variant options
+type ButtonIntent = "primary" | "secondary";
+type ButtonSize = "md" | "lg";
+
+// 4. Create component props interface extending variants
+interface ButtonProps extends ButtonVariants {
+  label: string;
+  onClick: () => void;
+  className?: string;
+}
+```
+
+When to use `type` vs `interface`:
+
+- `type`: For VariantProps, union types, and type aliases
+- `interface`: For component props (always extends variants)
+- `export`: Export interfaces for public component APIs
+
+Best Practices:
+
+- Always extend `VariantProps` for styled components
+- Define union types for variant options to ensure type safety
+- Export prop interfaces for components
+- Use strict TypeScript (enabled by default)
+
+### Project Structure
+
+Components and their Storybook stories are co-located in the same folder for better organization:
+
+```
+src/components/
+├── button/
+│   ├── Button.tsx           # Component implementation
+│   ├── Button.stories.tsx   # Storybook stories
+│   └── Button.test.tsx      # Unit tests (if applicable)
+├── avatar/
+│   ├── Avatar.tsx
+│   └── Avatar.stories.tsx
+└── ...
+```
+
+Benefits of co-location:
+
+- ✅ Related files stay together
+- ✅ Easier to find and maintain stories
+- ✅ Clear 1:1 relationship between components and documentation
+- ✅ Stories serve as living documentation and examples
+
+Story file naming: Always use `ComponentName.stories.tsx` format for Storybook to auto-discover them.
+
+---
+
+## Icon Generation
+
+SVG icons are automatically converted to React components with proper accessibility support.
+
+### Workflow
+
+1. Add SVG files to `src/components/icons/svg/`
+2. Optimize SVGs (optional but recommended):
+   ```bash
+   npx svgo -f src/components/icons/svg
+   ```
+3. Generate React components:
+   ```bash
+   npm run icons:generate
+   ```
+
+### Configuration
+
+Edit `svg.config.json` to customize the generation process:
+
+```json
+{
+  "sourceDir": "src/components/icons/svg",
+  "outputDir": "src/components/icons/generated",
+  "baseComponentImport": {
+    "name": "IconBase",
+    "path": "../IconBase"
+  }
+}
+```
+
+### Usage Example
+
+```tsx
+import { Calendar, LogOut } from "src/components/icons/generated";
+
+export function Example() {
+  return (
+    <div className="flex gap-2 text-slate-600">
+      <Calendar />
+      <LogOut className="text-red-600" />
+    </div>
+  );
+}
+```
+
+How it works:
+
+- File names are converted to PascalCase (`log-out.svg` → `LogOut`)
+- Fill colors are normalized to `currentColor` for theming
+- All icons are wrapped in `IconBase` for accessibility
+- A barrel export (`index.ts`) is generated automatically
+
+---
+
+## Visual Testing
+
+We use Playwright for visual regression testing against Storybook. Tests run in Docker for consistent results across environments.
+
+### Setup
+
+Build the Docker image (first time only):
+
+```bash
+npm run e2e:build
+```
+
+### Running Tests
+
+```bash
+npm run e2e:test         # Run visual regression tests
+npm run e2e:update       # Update baseline snapshots
+```
+
+### Viewing Reports
+
+View test reports locally:
+
+```bash
+npx playwright show-report
+```
+
+GitHub Artifacts:
+Test reports are uploaded as CI artifacts. Download and view them with:
+
+```bash
+npx playwright show-report <path/to/extracted-artifact>
+```
+
+### Configuration
+
+- Docker: Tests run in containers for consistency across environments
+- Network: Storybook accepts connections from `host.docker.internal`
+- Tolerance: 1% pixel difference allowed (`maxDiffPixelRatio: 0.01`)
+- Files: `playwright.config.ts` and `.storybook/main.ts`
+
+---
+
+## Contributing
+
+### Pull Request Process
+
+1. Create a feature branch:
+
+   ```bash
+   git checkout -b feature/initials/your-feature-name
+   ```
+
+   Use format: `feature/<mm or ci>/<description>`
+
+2. Make your changes and ensure quality:
+
+   ```bash
+   npm run preflight
+   ```
+
+3. Commit with conventional commits (see below)
+
+4. Push to your feature branch:
+
+   ```bash
+   git push origin feature/initials/your-feature-name
+   ```
+
+5. Create a pull request to `main`
+
+6. Wait for CI checks to pass
+
+7. Request review from team members
+
+8. Address feedback and merge
+
+### Commit Messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) for consistent versioning and changelog generation.
+
+Format:
+
+```
+<type>: <description>
+
+[optional body]
+```
+
+Types:
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style/formatting (no logic change)
+- `refactor`: Code refactoring (no feature/bug change)
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks (dependencies, config, etc.)
+- `perf`: Performance improvements
+
+Examples:
+
+```
+feat: add new Button variant
+fix: correct Typography component spacing
+docs: update README with visual testing guide
+chore: update dependencies
+test: add tests for TextLink component
+```
+
+---
+
+## Continuous Integration
+
+All pull requests are automatically validated through our CI pipeline.
+
+### Required Checks
+
+1. ✅ Format & Lint - Code must be properly formatted and pass linting
+2. ✅ Type Check - No TypeScript errors
+3. ✅ Tests - All unit tests must pass
+4. ✅ Build - Project must build successfully
+5. ✅ Build Storybook - Storybook must build successfully
+6. ✅ Visual Tests - Playwright visual regression tests must pass
+
+### Pipeline Triggers
+
+- Pull requests to `main`
+- Pushes to `main`
+
+### Why No Pre-commit Hooks?
+
+We intentionally don't use pre-commit hooks (like Husky):
+
+- ✅ Quality checks in CI can't be bypassed
+- ✅ Faster local development workflow
+- ✅ CI is the single source of truth
+
+Note: You're encouraged to run `npm run preflight` locally before pushing!
+
+---
+
+## EditorConfig & VS Code Settings
+
+This project uses a strict `.editorconfig` to ensure consistent code style across all editors and platforms. Most formatting rules (indentation, line endings, trailing whitespace, etc.) are enforced automatically if you have the [EditorConfig extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) installed in VS Code.
+
+Additionally, the repository includes a `.vscode/settings.json` file to avoid conflicts between VS Code's built-in formatting and EditorConfig:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "files.trimTrailingWhitespace": false,
+  "files.insertFinalNewline": false,
+  "files.eol": "\n"
+}
+```
+
+- No further VS Code settings are required—just make sure the EditorConfig extension is enabled.
+- These settings ensure that formatting is always consistent, regardless of individual developer/editor preferences.

package/dist/components/avatar/Avatar.d.ts

@@ -0,0 +1,71 @@
+import { type VariantProps } from "tailwind-variants";
+declare const avatarStyles: import("tailwind-variants").TVReturnType<{
+    size: {
+        sm: {
+            avatar: string[];
+        };
+        md: {
+            avatar: string[];
+        };
+        lg: {
+            avatar: string[];
+        };
+        xl: {
+            avatar: string[];
+        };
+    };
+}, {
+    base: string[];
+    avatar: string[];
+    action: string[];
+}, undefined, {
+    size: {
+        sm: {
+            avatar: string[];
+        };
+        md: {
+            avatar: string[];
+        };
+        lg: {
+            avatar: string[];
+        };
+        xl: {
+            avatar: string[];
+        };
+    };
+}, {
+    base: string[];
+    avatar: string[];
+    action: string[];
+}, import("tailwind-variants").TVReturnType<{
+    size: {
+        sm: {
+            avatar: string[];
+        };
+        md: {
+            avatar: string[];
+        };
+        lg: {
+            avatar: string[];
+        };
+        xl: {
+            avatar: string[];
+        };
+    };
+}, {
+    base: string[];
+    avatar: string[];
+    action: string[];
+}, undefined, unknown, unknown, undefined>>;
+type AvatarVariants = VariantProps<typeof avatarStyles>;
+type AvatarSize = "sm" | "md" | "lg" | "xl";
+interface AvatarProps extends AvatarVariants {
+    label: string;
+    size: AvatarSize;
+    src: string;
+    children: React.ReactNode;
+    onClick?: () => void;
+    onActionClick?: () => void;
+}
+export declare const Avatar: (props: AvatarProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/avatar/Avatar.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as RadixAvatar from "@radix-ui/react-avatar";
+import { tv } from "tailwind-variants";
+import { Edit } from "../icons/generated";
+import { RoundButton } from "../round-button/RoundButton";
+const avatarStyles = tv({
+    slots: {
+        base: ["relative", "inline-block"],
+        avatar: [
+            "rounded-full",
+            "transition",
+            "duration-300",
+            "ease-in-out",
+            "min-w-10",
+            "min-h-10",
+            "flex",
+            "items-center",
+            "justify-center",
+        ],
+        action: ["absolute", "bottom-2", "right-2"],
+    },
+    variants: {
+        size: {
+            sm: { avatar: ["w-10", "h-10", "hover:scale-105"] },
+            md: {
+                avatar: [
+                    "w-16",
+                    "h-16",
+                    "border",
+                    "border-solid",
+                    "border-slate-100",
+                    "border-6",
+                    "hover:scale-105",
+                ],
+            },
+            lg: {
+                avatar: [
+                    "w-24",
+                    "h-24",
+                    "border",
+                    "border-solid",
+                    "border-slate-100",
+                    "border-6",
+                    "hover:scale-95",
+                ],
+            },
+            xl: {
+                avatar: [
+                    "w-40",
+                    "h-40",
+                    "border",
+                    "border-solid",
+                    "border-slate-100",
+                    "border-6",
+                ],
+            },
+        },
+    },
+});
+export const Avatar = (props) => {
+    const { base, avatar, action } = avatarStyles(props);
+    return (_jsxs(RadixAvatar.Root, { onClick: props.onClick, className: base(props), children: [_jsx(RadixAvatar.Image, { src: props.src, alt: props.label, className: avatar(props) }), props.size === "xl" && props.onActionClick && (_jsx("div", { className: action(props), children: _jsx(RoundButton, { intent: "primary", ariaLabel: `Edit ${props.label}`, onClick: props.onActionClick ?? (() => { }), children: _jsx(Edit, {}) }) })), _jsx(RadixAvatar.Fallback, { children: _jsx("div", { className: avatar(props), children: props.children }) })] }));
+};

package/dist/components/branding/BrandingGallery.d.ts

@@ -0,0 +1 @@
+export declare const BrandingGallery: React.FC;

package/dist/components/branding/BrandingGallery.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import appIconGradient from "./app-icon-gradient.svg";
+import appIconWhite from "./app-icon-white.svg";
+import hoverLogo from "./hover-logo.svg";
+import logoInlineGradient from "./logo-inline-gradient.svg";
+import logoInlineViolet from "./logo-inline-violet.svg";
+import logoInlineWhite from "./logo-inline-white.svg";
+import logoStackedGradient from "./logo-stacked-gradient.svg";
+import logoStackedViolet from "./logo-stacked-violet.svg";
+import logoStackedWhite from "./logo-stacked-white.svg";
+import superzeichen from "./superzeichen.svg";
+const brandingAssets = {
+    "App Icons": [
+        {
+            name: "App Icon Gradient",
+            src: appIconGradient,
+            width: 64,
+            height: 64,
+            filename: "app-icon-gradient.svg",
+        },
+        {
+            name: "App Icon White",
+            src: appIconWhite,
+            width: 64,
+            height: 64,
+            filename: "app-icon-white.svg",
+        },
+    ],
+    Logos: [
+        {
+            name: "Logo Inline Gradient",
+            src: logoInlineGradient,
+            width: 335,
+            height: 64,
+            filename: "logo-inline-gradient.svg",
+        },
+        {
+            name: "Logo Inline Violet",
+            src: logoInlineViolet,
+            width: 335,
+            height: 64,
+            filename: "logo-inline-violet.svg",
+        },
+        {
+            name: "Logo Inline White",
+            src: logoInlineWhite,
+            width: 335,
+            height: 64,
+            filename: "logo-inline-white.svg",
+        },
+        {
+            name: "Logo Stacked Gradient",
+            src: logoStackedGradient,
+            width: 210,
+            height: 80,
+            filename: "logo-stacked-gradient.svg",
+        },
+        {
+            name: "Logo Stacked Violet",
+            src: logoStackedViolet,
+            width: 210,
+            height: 80,
+            filename: "logo-stacked-violet.svg",
+        },
+        {
+            name: "Logo Stacked White",
+            src: logoStackedWhite,
+            width: 210,
+            height: 80,
+            filename: "logo-stacked-white.svg",
+        },
+    ],
+    "Hover Logo": [
+        {
+            name: "Hover Logo",
+            src: hoverLogo,
+            width: 64,
+            height: 64,
+            filename: "hover-logo.svg",
+        },
+    ],
+    Superzeichen: [
+        {
+            name: "Superzeichen",
+            src: superzeichen,
+            width: 64,
+            height: 64,
+            filename: "superzeichen.svg",
+        },
+    ],
+};
+export const BrandingGallery = () => (_jsx("div", { children: Object.entries(brandingAssets).map(([category, assets]) => (_jsxs("div", { style: { marginBottom: 48 }, children: [_jsx("h2", { style: {
+                    fontSize: 20,
+                    fontWeight: 600,
+                    marginBottom: 24,
+                    marginTop: 0,
+                }, children: category }), _jsx("div", { style: {
+                    display: "grid",
+                    gridTemplateColumns: "repeat(auto-fill, minmax(300px, 1fr))",
+                    gap: 32,
+                    padding: 4,
+                }, children: assets.map(({ name, src, width, height, filename }) => {
+                    const isWhiteVariant = filename.includes("white") || filename.includes("hover");
+                    return (_jsxs("div", { style: {
+                            display: "flex",
+                            flexDirection: "column",
+                            alignItems: "center",
+                            border: "1px solid #eee",
+                            padding: 24,
+                            borderRadius: 8,
+                            backgroundColor: "#fafafa",
+                            gap: 16,
+                        }, children: [_jsx("div", { style: {
+                                    display: "flex",
+                                    alignItems: "center",
+                                    justifyContent: "center",
+                                    minHeight: 120,
+                                    width: "100%",
+                                    backgroundColor: isWhiteVariant ? "#7c3aed" : "transparent",
+                                    borderRadius: 4,
+                                    padding: isWhiteVariant ? 16 : 0,
+                                }, children: _jsx("img", { src: src, alt: name, style: {
+                                        maxWidth: "100%",
+                                        height: "auto",
+                                        objectFit: "contain",
+                                    } }) }), _jsxs("div", { style: {
+                                    textAlign: "center",
+                                    width: "100%",
+                                }, children: [_jsx("div", { style: { fontWeight: 600, marginBottom: 8 }, children: name }), _jsx("code", { style: {
+                                            fontSize: 11,
+                                            color: "#666",
+                                            display: "block",
+                                            marginBottom: 4,
+                                        }, children: filename }), _jsxs("code", { style: {
+                                            fontSize: 11,
+                                            color: "#666",
+                                            display: "block",
+                                        }, children: [width, " \u00D7 ", height] })] })] }, name));
+                }) })] }, category))) }));