npm package: @inadigital-ui/react
Description: **INA Digital Design System** adalah pustaka komponen UI berbasis React dan Tailwind CSS v4 yang siap di-publish ke NPM dan di‑consume oleh berbagai proyek.
Latest version: 1.1.83

# INA Digital Design System

**INA Digital Design System** adalah pustaka komponen UI berbasis React dan Tailwind CSS v4 yang siap di-publish ke NPM dan di‑consume oleh berbagai proyek.

---

## Daftar Isi Cara Menggunakan Project Design System

1. [Instalasi Design System](#instalasi-design-system)

- [A. Astro Project](#a-astro-project)
- [B. React Project`](#b-react-project)

## Instalasi Design System

```bash
# Pasang Tailwind CSS v4 beserta plugin Vite dan @tabler/icons-react yang digunakan untuk keperluan penggunaan icons agar lebih mudah
npm install @inadigital-ui/react tailwindcss@4.1.6 @tailwindcss/vite@4.1.6 @tabler/icons-react
# atau menggunakan Yarn
yarn add @inadigital-ui/react tailwindcss@4.1.6 @tailwindcss/vite@4.1.6 @tabler/icons-react
```

### A. Astro Project

1. Pastikan anda telah menginstall `@astrojs/react^4.2.7`, `react^18.0.0`, dan `react-dom^18.0.0`
2. Buat file **tailwind.config**, lalu import createPreset serta input nama brand yang hendak Anda pilih. Misal : BGN
   ```ts
   import createPreset from '@inadigital-ui/react/tailwind.preset.js';
   export default {
     darkMode: 'class',
     presets: [createPreset({ brand: 'BGN' })],
     theme: {
       // anda tetap diperbolehkan untuk melakukan customization variable yang belum tercover di design-system
       extend: {
         spacing: {
           '0.5': '2px',
           '1.5': '6px',
           '2.5': '10px',
           '3.5': '14px',
         },
       },
     },
     plugins: [],
   };
   ```
3. Di file global CSS anda, misal di `src/styles/global.css`, import plugin Tailwind agar utilitas tailwind bisa di gunakan sertakan juga `@config` dari **tailwind.config** nya agar custom theme & preset design system yang telah kita definisikan bisa terpakai.
   ```ts
    @import "tailwindcss";
    @config '../../tailwind.config.ts';
   ```
4. Import file CSS dari design system pada root file `.astro` Anda (yang terdapat tag `<html></html>` nya). Misal di src/layout/BaseLayout.astro. Pastikan Anda mengimport nya sebelum global CSS

```tsx
  ---
  import { SITE_TITLE, SITE_DESCRIPTION } from '../constants';
  import '@inadigital-ui/react/style.css';
  import '../styles/global.css';
  ---

  <!doctype html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>{SITE_TITLE}</title>

      <meta name="generator" content={Astro.generator} />
      <meta name="description" content={SITE_DESCRIPTION} />
      <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
      <link rel="sitemap" type="application/xml" href="/sitemap-index.xml" />
    </head>
    <body
      class:list={[
        'pb-10',
        'bg-gray-50 dark:bg-gray-800',
        'scrollbar scrollbar-w-3 scrollbar-thumb-rounded-[0.25rem]',
        'scrollbar-track-slate-200  scrollbar-thumb-gray-400',
        'dark:scrollbar-track-gray-900 dark:scrollbar-thumb-gray-700',
      ]}
    >
      <slot />
    </body>
  </html>

  <script></script>

  <style is:global>
    @import url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&family=Urbanist:ital,wght@0,100..900;1,100..900&display=swap');
  </style>
```

### B. React Project

1. Pastikan anda telah menginstall `react^18.0.0`, dan `react-dom^18.0.0`
2. Buat file **tailwind.config**, lalu import createPreset serta input nama brand yang hendak Anda pilih. Misal : BGN

   ```ts
   // tailwind.config.js
   import createPreset from '@inadigital-ui/react/tailwind.preset.js';

   /** @type {import('tailwindcss').Config} */
   export default {
     presets: [createPreset({ brand: 'BGN' })],
     content: [
       './index.html',
       './src/**/*.{js,ts,jsx,tsx}',
       './*.{js,ts,jsx,tsx}',
     ],
     theme: {
       extend: {
         backgroundImage: {},
         colors: {},
         fontSize: {},
       },
     },
     plugins: [],
   };
   ```

3. Di file global CSS anda, misal di `src/index.css`, import plugin Tailwind agar utilitas tailwind bisa di gunakan sertakan juga `@config` dari **tailwind.config** nya agar custom theme & preset design system yang telah kita definisikan bisa terpakai.
   ```ts
    @import "tailwindcss";
    @config '../../tailwind.config.ts';
   ```
4. Import file CSS dari design system pada root file `.jsx/.tsx` dari project React Anda. Misal menggunakan vite, maka ada di `src/main.jsx` seperti contoh dibawah ini :

```jsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import '@inadigital-ui/react/style.css';
import './index.css';
import App from './App.jsx';

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>
);
```

---

## Daftar Isi Penjelasan Project Design System

**_(Just For Knowledge &amp; Documentation Purpose, Don't Implement It In Your Project)_**

1. [Prasyarat](#prasyarat)
2. [Instalasi](#instalasi)
3. [Konfigurasi Vite & Tailwind](#konfigurasi-vite--tailwind)

   - [1. Install Tailwind & Plugin](#1-install-tailwind--plugin)
   - [2. Setup `vite.config.ts`](#2-setup-viteconfigts)
   - [3. Prettier & VS Code Settings](#3-prettier--vs-code-settings)

4. [Struktur Tailwind Config](#struktur-tailwind-config)

   - [Preset vs Config](#preset-vs-config)

5. [TypeScript Config](#typescript-config)
6. [Asset Font Internal](#asset-font-internal)
7. [Global CSS](#global-css)
8. [Publikasi ke NPM](#publikasi-ke-npm)
9. [License](#license)

---

## Prasyarat

- Node.js ≥ 16
- NPM / Yarn
- React & ReactDOM

---

## Instalasi

```bash
# Pasang Tailwind CSS v4 dan plugin Vite
npm install tailwindcss@latest @tailwindcss/vite @tabler/icons-react
# atau menggunakan Yarn
yarn add tailwindcss@latest @tailwindcss/vite @tabler/icons-react
```

---

## Konfigurasi Vite & Tailwind

### 1. Install Tailwind & Plugin

1. Jalankan perintah instalasi di atas.
2. Di file `vite.config.ts`, import plugin Tailwind untuk Vite:

   ```ts
   import tailwindcss from '@tailwindcss/vite';
   ```

### 2. Setup `vite.config.ts`

“Externalizing React” artinya menandai paket React (dan runtime JSX‑nya) sebagai external dalam build library-mu, sehingga tidak dibundel ke dalam output final. Sebagai gantinya, library-mu akan mengandalkan React yang diinstal oleh consumer (proyek yang menggunakan library). Ini mencegah duplikasi React di bundle, menghindari mismatched internals seperti error ReactCurrentDispatcher di Astro, dan menjaga ukuran bundle tetap kecil.

Mengapa perlu externalize React?

1. **Duplikasi React**
   Jika library dan aplikasi utama sama‑sama membundel React, akan ada dua instance React di page yang dapat memicu hook/context breakage (mis. ReactCurrentDispatcher undefined) .

2. **Ukuran Bundle**
   Eksternalisasi mencegah React ditambahkan ke package output, membuat library ringan dan berpindah‑pindah antar proyek tanpa membawa React.

3. **Single source of React**
   Consumer project bertanggung jawab menginstal versi React mereka sendiri, menjaga kompatibilitas dan konsistensi.

Tambahkan konfigurasi build dan external dependency React/ReactDOM:

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  build: {
    lib: {
      entry: './src/index.ts',
      name: 'INADigitalDesignSystem',
      formats: ['es', 'umd'],
      fileName: (format) => `@inadigital-ui/react.${format}.js`,
    },
    rollupOptions: {
      external: [
        'react',
        'react-dom',
        'react/jsx-runtime',
        'react-dom/client', // untuk React 18+ jika kamu pakai createRoot
      ],
      output: {
        // ② Beri tahu global names untuk UMD/IIFE (jika dipakai)
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
          'react/jsx-runtime': 'jsxRuntime',
          'react-dom/client': 'ReactDOMClient',
        },
      },
    },
  },
});
```

### 3. Prettier & VS Code Settings

- Aktifkan ekstensi **Prettier** di VS Code.
- (Opsional) Buat file `.vscode/settings.json` di root project untuk custom language support Tailwind:

  ```json
  {
    "tailwindCSS.includeLanguages": {
      "typescript": "javascript",
      "typescriptreact": "javascriptreact"
    },
    "editor.formatOnSave": true,
    "tailwindCSS.classAttributes": ["class", "class:list", "className"],
    // Suruh Tailwind IntelliSense mem-parse file global.css sebagai config
    "tailwindCSS.experimental.configFile": "src/index.css"
  }
  ```

---

## Struktur Tailwind Config

Kita menggunakan dua file konfigurasi:

1. **`tailwind.preset.ts`**

   - Digunakan sebagai _preset_ eksternal.
   - Definisikan brand colors, font family, spacing, dll.
   - File ini akan di-_export_ dan dikonsumsi oleh project lain.

2. **`tailwind.config.ts`**

   - Konfigurasi internal project Design System.
   - Merujuk ke `tailwind.preset.ts` sebagai _source of truth_ agar tidak duplikasi (DRY).

Contoh `tailwind.preset.ts`:

```ts
import { Preset } from 'tailwindcss';

const preset: Preset = {
  theme: {
    colors: {
      primary: '#1DA1F2',
      secondary: '#14171A',
      // … lainnya
    },
    fontFamily: {
      sans: ['Inter', 'sans-serif'],
    },
  },
};

export default preset;
```

Contoh `tailwind.config.ts`:

```ts
import preset from './tailwind.preset';

export default {
  presets: [preset],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
};
```

---

## TypeScript Config

Pisahkan `tsconfig` menjadi dua:

- **`tsconfig.app.json`**
  Untuk build aplikasi React (pastikan `module` & `moduleResolution` = `nodenext`).

- **`tsconfig.node.json`**
  Untuk keperluan _scripts_ atau _build tools_ di Node.js.

---

## Asset Font Internal

Kami menyertakan file font `.woff2` di dalam project:

```
src/
└── assets/
    └── fonts/
        └── Inter/
            ├── Inter-Regular.woff2
            ├── Inter-Bold.woff2
            └── … lainnya
```

---

## Global CSS

1. Buat file `src/assets/fonts.css` untuk _@font-face_:

   ```css
   @font-face {
     font-family: 'Inter';
     src: url('../fonts/Inter/Inter-Regular.woff2') format('woff2');
     font-weight: 400;
     font-style: normal;
   }
   /* … weight lainnya */
   ```

2. Di `src/index.css`:

   ```css
   @import 'tailwindcss/base';
   @import 'tailwindcss/components';
   @import 'tailwindcss/utilities';

   @import './assets/fonts.css';

   /* Link ke konfigurasi Tailwind */
   @config './tailwind.config.ts';
   ```

---

## Publikasi ke NPM

Pastikan di `package.json` terdapat field berikut:

```jsonc
{
  "name": "@inadigital-ui/react",
  "version": "0.6.21",
  "type": "module",
  "main": "dist/@inadigital-ui/react.umd.js",
  "module": "dist/@inadigital-ui/react.es.js",
  "types": "dist/types/index.d.ts",
  "files": ["dist", "dist/tailwind.preset.js"],
  "scripts": {
    "build:css": "npx @tailwindcss/cli -i src/index.css -o dist/style.css --minify",
    "build:preset": "tsc --project tsconfig.preset.json",
    "build": "tsc --project tsconfig.app.json && vite build && npm run build:preset && npm run build:css"
  },
  "peerDependencies": {
    "react": ">=18.0.0", // gunakan >= untuk meminimalisir error missmatch react version antara design-system and consumer project
    "react-dom": ">=18.0.0"
  },
  "style": "dist/style.css", // agar saat consumer import "@inadigital-ui/react/style.css" maka akan di arahkan ke file yang ada didalam folder dist/style.css
  "exports": {
    ".": {
      "import": "./dist/@inadigital-ui/react.es.js",
      "require": "./dist/@inadigital-ui/react.umd.js",
      "types": "./dist/types/index.d.ts"
    },
    "./tailwind.preset.js": {
      "import": "./dist/tailwind.preset.js",
      "require": "./dist/tailwind.preset.js"
    },
    "./style.css": {
      "import": "./dist/style.css",
      "require": "./dist/style.css"
    },
    "./*": "./dist/*"
  }
}
```

Publikasi:

```bash
npm run build
npm version patch
npm publish --access public
```

---

## License

INA Digital © \[Umar Faruq]