npm package: @gftdcojp/ui
Description: AI GFTD Design System Components
Author: GFTD Co., Ltd.
Latest version: 1.9.6

# GFTD Design System Components

AI-powered design system components with Web Components support using r2wc.

## Features

- 🎨 **Complete Design System**: Comprehensive set of UI components
- 🌐 **Web Components**: Full Web Components support via r2wc
- ⚛️ **React Compatible**: Works seamlessly with React applications
- 🎯 **TypeScript**: Full TypeScript support
- 📦 **Multiple Formats**: ESM, CJS, and UMD builds available
- 🎨 **UnoCSS Integration**: Built-in UnoCSS configuration for utility-first CSS
- 🎨 **Tailwind CSS**: Supports Tailwind CSS v3 with integrated theme system
- 🎨 **Design Tokens**: Integrated with @digital-go-jp/design-tokens
- 🎨 **Theme Plugin**: Enhanced with @digital-go-jp/tailwind-theme-plugin
- 🚀 **Zero Config**: Install and use - UnoCSS configuration included

## 🚀 Quick Start with UnoCSS (Recommended)

This package includes **UnoCSS configuration out of the box**. Simply install the package and you're ready to use utility-first CSS!

```bash
# Install with UnoCSS (recommended)
npm install @gftdcojp/ui

# Or with pnpm
pnpm add @gftdcojp/ui
```

### UnoCSS Configuration

Import the built-in UnoCSS configuration:

```js
// unocss.config.js
import { defineConfig } from 'unocss'
import config from '@gftdcojp/ui/unocss.config'

export default defineConfig(config)
```

That's it! No additional configuration needed. The package includes:
- ✅ Pre-configured UnoCSS presets
- ✅ Integrated design tokens
- ✅ Theme-aware color system
- ✅ Typography utilities
- ✅ Component-specific utilities

## ⚠️ Alternative: Tailwind CSS v3 Setup

If you prefer to use Tailwind CSS v3 instead of UnoCSS, follow this configuration:

## Installation

```bash
# Using npm
npm install @gftdcojp/ui

# Using pnpm
pnpm add @gftdcojp/ui

# Using yarn
yarn add @gftdcojp/ui
```

### Required Dependencies for UnoCSS (Recommended)

```bash
# Install UnoCSS and the design system package
npm install @gftdcojp/ui

# Or with pnpm
pnpm add @gftdcojp/ui
```

**Note**: No additional dependencies required! UnoCSS and all presets are included.

### Alternative: Required Dependencies for Tailwind CSS v3

```bash
# Install Tailwind CSS v3 and required dependencies
npm install @gftdcojp/ui tailwindcss@^3.4.0 autoprefixer postcss @digital-go-jp/tailwind-theme-plugin

# Or with pnpm
pnpm add @gftdcojp/ui tailwindcss@^3.4.0 autoprefixer postcss @digital-go-jp/tailwind-theme-plugin
```

### Tailwind CSS v3 Configuration Example

Create or update your `tailwind.config.js` file:

```javascript
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    // Include the UI package components
    "./node_modules/@gftdcojp/ui/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      // Theme is handled by @digital-go-jp/tailwind-theme-plugin
      // All design tokens are automatically available
    },
  },
  plugins: [
    // GFTD Design System Theme Plugin
    require('@digital-go-jp/tailwind-theme-plugin'),
  ],
}
```

## 🎨 UnoCSS Usage Examples

With the built-in UnoCSS configuration, you can use design system utilities directly:

### Colors
```html
<!-- Design system colors -->
<div class="bg-blue-500 text-white">Primary Blue</div>
<div class="bg-green-500 text-white">Success Green</div>
<div class="bg-red-500 text-white">Error Red</div>

<!-- Solid gray scale -->
<div class="bg-solid-gray-50">Light Gray</div>
<div class="bg-solid-gray-900 text-white">Dark Gray</div>
```

### Typography
```html
<!-- Typography utilities -->
<h1 class="text-dsp-64B-140">Display Heading</h1>
<h2 class="text-std-45B-140">Standard Heading</h2>
<p class="text-dns-17N-130">Dense body text</p>

<!-- Font weights -->
<span class="font-400">Normal weight</span>
<span class="font-700">Bold weight</span>
```

### Spacing & Layout
```html
<!-- Spacing using base-8 scale -->
<div class="p-8 m-4">Padding and margin</div>
<div class="space-x-8 space-y-4">Space utilities</div>
```

### Responsive Design
```html
<!-- Responsive utilities -->
<div class="w-full md:w-1/2 lg:w-1/3">Responsive width</div>
<div class="text-16 md:text-18 lg:text-20">Responsive text</div>
```

### Component Integration
```jsx
import { Button } from '@gftdcojp/ui'

function MyComponent() {
  return (
    <div class="p-8 bg-solid-gray-50">
      <Button className="bg-blue-500 text-white hover:bg-blue-600">
        Click me
      </Button>
    </div>
  )
}
```

## 📝 Manual UnoCSS Configuration (Advanced)

For advanced use cases, you can extend the built-in configuration:

```js
// unocss.config.js
import { defineConfig } from 'unocss'
import baseConfig from '@gftdcojp/ui/unocss.config'

export default defineConfig({
  ...baseConfig,
  // Add your custom configuration
  theme: {
    ...baseConfig.theme,
    colors: {
      ...baseConfig.theme.colors,
      'brand': '#your-brand-color',
    }
  },
  rules: [
    // Add custom rules
    ['text-brand', { color: 'var(--brand-color)' }],
  ]
})
```

### PostCSS Configuration

Create or update your `postcss.config.js` file:

```javascript
// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
```

### CSS Imports

Add the following to your main CSS file (e.g., `globals.css` or `index.css`):

```css
/* Import Tailwind base styles */
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

/* Import GFTD theme CSS variables */
@import '@digital-go-jp/tailwind-theme-plugin/dist/theme.css';
```

### Example from @1010-demo-nextjs-tailwindv3

For a complete working example, see the [@1010-demo-nextjs-tailwindv3 application](https://github.com/gftdcojp/01010-ai-gftd-designsystem-components-main/tree/main/apps/1010-demo-nextjs-tailwindv3) which demonstrates proper Tailwind CSS v3 integration with this UI package.

## Usage

### As React Components (Default)

```tsx
import { Button, Input, Card } from '@gftdcojp/ui';

function App() {
  return (
    <div>
      <Button variant="solid-fill" size="md">Click me</Button>
      <Input placeholder="Enter text" />
      <Card>
        <CardHeader>
          <CardTitle>Card Title</CardTitle>
        </CardHeader>
        <CardContent>
          <p>Card content goes here.</p>
        </CardContent>
      </Card>
    </div>
  );
}
```

### As Web Components

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Load the Web Components bundle -->
  <script type="module" src="https://unpkg.com/@gftdcojp/ui/web-components"></script>
</head>
<body>
  <!-- Use components as custom elements -->
  <gftd-button variant="solid-fill" size="md">Click me</gftd-button>
  <gftd-input placeholder="Enter text"></gftd-input>
  <gftd-card>
    <div slot="header">
      <h3>Card Title</h3>
    </div>
    <div slot="content">
      <p>Card content goes here.</p>
    </div>
  </gftd-card>
</body>
</html>
```

### In JavaScript/TypeScript

```javascript
// ESM import
import { Button, Input } from '@gftdcojp/ui';

// CommonJS require
const { Button, Input } = require('@gftdcojp/ui');

// Web Components import
import '@gftdcojp/ui/web-components';
```

## Web Components API

All React components are automatically converted to Web Components with the following naming convention:

| React Component | Web Component |
|----------------|---------------|
| `Button` | `<gftd-button>` |
| `Input` | `<gftd-input>` |
| `Card` | `<gftd-card>` |
| `Alert` | `<gftd-alert>` |
| `Badge` | `<gftd-badge>` |
| `Checkbox` | `<gftd-checkbox>` |
| `Select` | `<gftd-select>` |
| `Textarea` | `<gftd-textarea>` |
| `Tabs` | `<gftd-tabs>` |
| `Tooltip` | `<gftd-tooltip>` |
| And many more... | |

### Component Props as Attributes

React component props are converted to HTML attributes:

```html
<!-- React: <Button variant="outline" size="lg" disabled>Click</Button> -->
<gftd-button variant="outline" size="lg" disabled>Click</gftd-button>

<!-- React: <Input placeholder="Enter name" required /> -->
<gftd-input placeholder="Enter name" required></gftd-input>
```

### Slots for Complex Content

Components with children use slots:

```html
<gftd-card>
  <div slot="header">
    <h3>My Card Title</h3>
  </div>
  <div slot="content">
    <p>Card content here.</p>
  </div>
  <div slot="footer">
    <button>Action</button>
  </div>
</gftd-card>
```

## Available Components

### Core Components
- **Button**: Interactive buttons with variants (solid-fill, outline, text)
- **Input**: Text input fields
- **Textarea**: Multi-line text input
- **Select**: Dropdown selection
- **Checkbox**: Checkboxes for boolean input
- **Radio**: Radio buttons for single selection

### Layout Components
- **Card**: Content containers with header, content, and footer
- **Accordion**: Collapsible content sections
- **Tabs**: Tabbed interface components
- **Collapsible**: Expandable/collapsible content
- **Divider**: Visual separators

### Feedback Components
- **Alert**: Notification messages
- **Badge**: Status indicators
- **Tooltip**: Contextual help
- **ProgressIndicator**: Progress bars
- **Skeleton**: Loading placeholders

### Form Components
- **Form**: Form containers
- **Label**: Form field labels
- **Legend**: Form section legends

### Navigation Components
- **Breadcrumbs**: Navigation breadcrumbs
- **NavigationMenu**: Navigation menus
- **Menubar**: Menu bars
- **MobileMenu**: Mobile navigation

### Data Display
- **Table**: Data tables
- **DataTable**: Advanced data tables
- **List**: Lists and list items
- **Avatar**: User avatars

### Overlay Components
- **ModalDialog**: Modal dialogs
- **Drawer**: Slide-out panels
- **Sheet**: Overlay sheets
- **Popover**: Popover content
- **HoverCard**: Hover-triggered cards
- **ContextMenu**: Context menus
- **DropdownMenu**: Dropdown menus

### Utility Components
- **Skeleton**: Loading states
- **Switch**: Toggle switches
- **Slider**: Range sliders
- **DatePicker**: Date selection
- **StatusBadge**: Status indicators
- **SupportText**: Helper text

## Build Configuration

The library supports multiple build formats:

### ESM (Recommended)
```javascript
import { Button } from '@gftdcojp/ui';
// or
import { Button } from '@gftdcojp/ui/dist/index.es.js';
```

### CommonJS
```javascript
const { Button } = require('@gftdcojp/ui');
// or
const { Button } = require('@gftdcojp/ui/dist/index.cjs.js');
```

### Web Components
```javascript
import '@gftdcojp/ui/web-components';
// or
import '@gftdcojp/ui/dist/web-components.es.js';
```

## Development

```bash
# Install dependencies
pnpm install

# Build the library
pnpm run build

# Run type checking
pnpm run typecheck

# Run linting
pnpm run lint

# Format code
pnpm run format
```

## Browser Support

The Web Components version works in all modern browsers that support:
- Custom Elements API
- ES6 Modules
- Shadow DOM (optional, but recommended)

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the build and tests
6. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Process Network

This project follows the GTS(DPO)+OpenGraph with Merkle DAG process network model:

- **Workspace Orchestration**: Monorepo management
- **UI Package**: Component library with Web Components transformation
- **Web Components Layer**: r2wc-powered Web Components export
- **Build Pipeline**: Automated build and transformation pipeline
- **Tailwind Integration**: Currently optimized for Tailwind CSS v3 with theme plugin support

Each component includes Merkle DAG annotations for process network integrity.

### Tailwind CSS v3 Integration in Process Network

The UI package integrates with Tailwind CSS v3 through the following process network nodes:

- **Theme Plugin Node**: `@digital-go-jp/tailwind-theme-plugin` provides design tokens
- **CSS Variables Node**: Theme values are exposed as CSS custom properties
- **Component Styling Node**: Components use Tailwind utilities and theme variables
- **Build Integration Node**: Ensures proper purging and optimization

For the complete Tailwind CSS v3 integration example, refer to the `@1010-demo-nextjs-tailwindv3` application in the monorepo.