@shohojdhara/atomix 0.1.17 → 0.1.20

package/CONTRIBUTING.md

@@ -0,0 +1,151 @@
+# Contributing to Atomix
+
+Thank you for your interest in contributing to Atomix! This document provides guidelines and instructions for contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Documentation](#documentation)
+
+## Code of Conduct
+
+We expect all contributors to follow our [Code of Conduct](./CODE_OF_CONDUCT.md). Please read it before participating.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (version 16 or higher)
+- npm (version 7 or higher)
+
+### Setup
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/atomix.git
+   cd atomix
+   ```
+3. Install dependencies
+   ```bash
+   npm install
+   ```
+4. Set up the development environment
+   ```bash
+   npm run dev
+   ```
+
+## Development Workflow
+
+### Branch Organization
+
+- `main` - The main development branch
+- `release/*` - Release branches
+- `feature/*` - Feature branches
+- `bugfix/*` - Bug fix branches
+
+### Working on Features
+
+1. Create a new branch from `main`
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. Make your changes
+3. Run tests and linting
+   ```bash
+   npm run test
+   npm run lint
+   ```
+4. Commit your changes with a descriptive commit message
+   ```bash
+   git commit -m "feat: add new feature"
+   ```
+   We follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.
+
+5. Push your branch to your fork
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Pull Request Process
+
+1. Update the README.md or documentation with details of changes if appropriate
+2. Update the CHANGELOG.md with details of changes
+3. The PR should work with the latest version of the codebase
+4. Include screenshots or animated GIFs in your PR if it includes visual changes
+5. Link any related issues in the PR description
+
+## Coding Standards
+
+### JavaScript/TypeScript
+
+- We use ESLint for linting
+- We follow the Airbnb JavaScript Style Guide with some modifications
+- Use TypeScript for all new code
+- Document public APIs with JSDoc comments
+
+### CSS/SCSS
+
+- We follow the BEM methodology for CSS naming
+- Use SCSS for all styling
+- Follow the ITCSS architecture for organizing styles
+
+### Component Guidelines
+
+Please refer to the [Atomix Component Guidelines](./atomix-component-guidelines.md) for detailed information on creating and modifying components.
+
+## Testing
+
+- Write tests for all new features and bug fixes
+- Run the test suite before submitting a PR
+  ```bash
+  npm run test
+  ```
+
+## Documentation
+
+- Update documentation for any changes to the API
+- Use markdown for documentation
+- Include examples for new features
+
+## Release Process
+
+### Version Management
+
+We use semantic versioning for releases. To bump the version:
+
+```bash
+# Patch release (bug fixes)
+npm run version:patch
+
+# Minor release (new features)
+npm run version:minor
+
+# Major release (breaking changes)
+npm run version:major
+```
+
+### Publishing
+
+For release candidates:
+
+```bash
+npm run publish:rc
+```
+
+For stable releases:
+
+```bash
+npm run publish:latest
+```
+
+## Questions?
+
+If you have any questions, please feel free to open an issue or contact the maintainers.
+
+Thank you for contributing to Atomix!

package/NEXTJS_INTEGRATION.md

@@ -0,0 +1,383 @@
+# Next.js Integration Guide
+
+This guide explains how to integrate Atomix Design System with Next.js applications, including support for Server-Side Rendering (SSR) and App Router.
+
+## Installation
+
+```bash
+npm install @shohojdhara/atomix
+# or
+yarn add @shohojdhara/atomix
+# or
+pnpm add @shohojdhara/atomix
+```
+
+## Basic Setup
+
+### 1. Import Styles
+
+Add the Atomix CSS to your Next.js application:
+
+#### App Router (app directory)
+```tsx
+// app/layout.tsx
+import '@shohojdhara/atomix/css'
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+#### Pages Router (pages directory)
+```tsx
+// pages/_app.tsx
+import '@shohojdhara/atomix/css'
+import type { AppProps } from 'next/app'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />
+}
+```
+
+### 2. Use Components
+
+```tsx
+// app/page.tsx or pages/index.tsx
+import { Button, Hero, Card } from '@shohojdhara/atomix'
+
+export default function HomePage() {
+  return (
+    <div>
+      <Hero
+        title="Welcome to Next.js with Atomix"
+        subtitle="Modern UI Components"
+        text="Build beautiful applications with Atomix Design System"
+        alignment="center"
+      />
+      
+      <div className="o-container u-py-5">
+        <Card>
+          <div className="c-card__body">
+            <h3 className="c-card__title">Getting Started</h3>
+            <p className="c-card__text">
+              Start building with Atomix components in your Next.js application.
+            </p>
+            <Button variant="primary" label="Learn More" />
+          </div>
+        </Card>
+      </div>
+    </div>
+  )
+}
+```
+
+## Advanced Configuration
+
+### Next.js Configuration
+
+Create or update your `next.config.js` file:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Transpile Atomix package for better compatibility
+  transpilePackages: ['@shohojdhara/atomix'],
+  
+  // Configure webpack for custom assets
+  webpack: (config, { isServer }) => {
+    // Handle SCSS files from Atomix
+    config.module.rules.push({
+      test: /\.scss$/,
+      use: [
+        'style-loader',
+        'css-loader',
+        {
+          loader: 'sass-loader',
+          options: {
+            implementation: require('sass-embedded'),
+          },
+        },
+      ],
+    });
+
+    // Handle TypeScript declaration files
+    config.module.rules.push({
+      test: /\.d\.ts$/,
+      exclude: /node_modules/,
+      use: [{ loader: 'ignore-loader' }]
+    });
+
+    // Add fallbacks for Node.js core modules (required for Webpack 5)
+    if (!isServer) {
+      config.resolve.fallback = {
+        ...config.resolve.fallback,
+        crypto: false, // Provide empty mock for crypto
+      };
+    }
+
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+```
+
+For the TypeScript declaration files fix, you'll need to install:
+
+```bash
+npm install --save-dev ignore-loader
+# or
+yarn add --dev ignore-loader
+# or
+pnpm add --save-dev ignore-loader
+```
+
+### TypeScript Configuration
+
+Ensure your `tsconfig.json` includes proper module resolution:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "jsx": "preserve"
+  }
+}
+```
+
+## Server-Side Rendering (SSR) Support
+
+Atomix components are fully compatible with Next.js SSR. All components render correctly on the server and hydrate properly on the client.
+
+### Dynamic Imports (if needed)
+
+For components with client-side only features, use dynamic imports:
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const DynamicComponent = dynamic(
+  () => import('@shohojdhara/atomix').then(mod => mod.ComponentName),
+  { ssr: false }
+)
+```
+
+## Styling Options
+
+### 1. Using Pre-built CSS
+
+```tsx
+import '@shohojdhara/atomix/css'
+// or minified version
+import '@shohojdhara/atomix/css/min'
+```
+
+### 2. Using SCSS (for customization)
+
+```scss
+// styles/globals.scss
+@import '@shohojdhara/atomix/scss';
+
+// Your custom overrides
+:root {
+  --atomix-primary-color: #your-brand-color;
+}
+```
+
+### 3. CSS Modules Support
+
+Atomix works seamlessly with Next.js CSS Modules:
+
+```tsx
+// components/MyComponent.module.scss
+.container {
+  @apply u-p-4 u-bg-primary-subtle;
+}
+
+.title {
+  @apply c-hero__title;
+}
+```
+
+## Theme Configuration
+
+### Dark Mode Support
+
+```tsx
+// app/layout.tsx
+'use client'
+import { useEffect, useState } from 'react'
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const [theme, setTheme] = useState('light')
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-atomix-theme', theme)
+  }, [theme])
+
+  return (
+    <html lang="en" data-atomix-theme={theme}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+### Custom Theme Variables
+
+```css
+/* styles/globals.css */
+:root {
+  /* Primary Colors */
+  --atomix-primary-50: #eff6ff;
+  --atomix-primary-500: #3b82f6;
+  --atomix-primary-900: #1e3a8a;
+  
+  /* Custom spacing */
+  --atomix-spacing-xs: 0.25rem;
+  --atomix-spacing-sm: 0.5rem;
+  --atomix-spacing-md: 1rem;
+}
+```
+
+## Performance Optimization
+
+### Tree Shaking
+
+Atomix supports tree shaking out of the box. Import only the components you need:
+
+```tsx
+// ✅ Good - tree shaking works
+import { Button, Card } from '@shohojdhara/atomix'
+
+// ❌ Avoid - imports entire library
+import * as Atomix from '@shohojdhara/atomix'
+```
+
+### Bundle Analysis
+
+Use Next.js bundle analyzer to check your bundle size:
+
+```bash
+npm install --save-dev @next/bundle-analyzer
+```
+
+```javascript
+// next.config.js
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+})
+
+module.exports = withBundleAnalyzer(nextConfig)
+```
+
+## Common Issues and Solutions
+
+### 1. CSS Not Loading
+
+Make sure to import the CSS file in your root layout or _app file:
+
+```tsx
+import '@shohojdhara/atomix/css'
+```
+
+### 2. TypeScript Errors
+
+Ensure you have the latest TypeScript definitions:
+
+```bash
+npm install --save-dev @types/react @types/react-dom
+```
+
+### 3. Hydration Mismatches
+
+For components with dynamic content, use the `suppressHydrationWarning` prop:
+
+```tsx
+<div suppressHydrationWarning>
+  {/* Dynamic content */}
+</div>
+```
+
+### 4. Font Loading Issues
+
+If using custom fonts, add them to your Next.js font optimization:
+
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>{children}</body>
+    </html>
+  )
+}
+```
+
+## Example Projects
+
+### Minimal Setup
+
+```tsx
+// app/page.tsx
+import { Button, Hero } from '@shohojdhara/atomix'
+
+export default function Home() {
+  return (
+    <Hero
+      title="Hello Next.js + Atomix"
+      actions={<Button variant="primary" label="Get Started" />}
+    />
+  )
+}
+```
+
+### Full Application Structure
+
+```
+my-nextjs-app/
+├── app/
+│   ├── layout.tsx          # Import Atomix CSS here
+│   ├── page.tsx           # Use Atomix components
+│   └── globals.css        # Custom theme variables
+├── components/
+│   └── ui/                # Your custom components using Atomix
+├── next.config.js         # Next.js configuration
+└── package.json
+```
+
+## Migration from Other UI Libraries
+
+If you're migrating from other UI libraries, Atomix provides similar components with consistent APIs. Check our [Component Migration Guide](./MIGRATION.md) for specific mappings.
+
+## Support
+
+- [Documentation](https://liimonx.github.io/atomix)
+- [Storybook](https://liimonx.github.io/atomix/storybook)
+- [GitHub Issues](https://github.com/liimonx/atomix/issues)
+
+## Contributing
+
+See our [Contributing Guide](./CONTRIBUTING.md) for information on how to contribute to Atomix.