@talentlytica/prodigy

Design system Talentlytica Prodigy — berbasis Mantine v9 dengan tema Kelola Apps. Package pnpm (library ESM + type declarations); dokumentasi komponen berjalan di Storybook 10.

Satu tema (Kelola), satu layer komponen. Token hidup di src/themes/kelola.ts; komponen (src/components) tinggal re-export Mantine dengan default terkunci di theme.

Audit sumber: ../design-system-kelola.md (Kelola). Arsip audit Integro (fase testing awal): ../design-system.md.

Menjalankan

Prasyarat: Node.js ≥ 20.19 atau ≥ 22.12 (wajib untuk Storybook 10 + Vite 8).

cd prodigy-ui
pnpm install
pnpm storybook          # dev docs → http://localhost:6006
pnpm build              # build library → dist/ (ESM + .d.ts)

Perintah lain: pnpm build-storybook (docs statis), pnpm typecheck.

Sudah diverifikasi di Node 20.20.2: build-storybook sukses & tsc --noEmit bersih.

Kenapa dibuat begini (anti-fragmentasi)

Isu di Kelola: styling melewati theme — ribuan inline style=, UnstyledButton dipakai jauh lebih banyak dari Button, plus sistem tipografi/utility paralel. Prodigy mencegahnya lewat tiga lapis:

1. Theme mengunci default — src/themes/kelola.ts memakai Component.extend({ defaultProps }). Semua keputusan visual default ada di satu tempat.
2. Satu pintu import — komponen di-export dari paket ini (src/components). Aplikasi tidak import dari @mantine/core langsung.
3. Lint guard — eslint.config.js melarang impor @mantine/core di luar design system (no-restricted-imports). Aktifkan: pnpm add -D eslint && pnpm eslint src.

Props tetap 100% API Mantine → tidak ada API baru untuk dihafal, dan tabel props di Storybook (Controls) mengikuti Mantine.

Arsitektur

Tiap komponen adalah re-export tipis dari Mantine (menjaga tipe polimorfik tetap utuh); "keputusan visual" ditaruh di theme, bukan di tiap wrapper.

prodigy-ui/
├─ .storybook/            # main.ts, preview.tsx (MantineProvider + toggle light/dark), preview-head.html (font)
├─ src/
│  ├─ themes/             # kelola.ts · index.ts — token + defaultProps (tema Kelola)
│  ├─ theme.ts            # kompat: re-export theme
│  ├─ index.ts            # entry paket
│  ├─ components/
│  │  ├─ index.ts         # barrel (satu pintu import)
│  │  ├─ primitives.ts    # Group/Stack/Flex/Grid/Text/Title … (re-export)
│  │  └─ <Nama>/<Nama>.tsx + <Nama>.stories.tsx
│  └─ stories/            # Foundations (Colors, Typography, Spacing, Shadows, Radius, Icons) + Layout/Primitives
├─ postcss.config.cjs     # wajib untuk Mantine (preset + breakpoints)
└─ eslint.config.js       # lint guard anti-fragmentasi

Komponen (55) + primitives (12)

Kategori mengikuti struktur kontekstual Mantine sendiri (bukan atoms/molecules) — lihat Introduction. Komponen bertanda † butuh paket ekstensi opsional tambahan (peer dependency di luar @mantine/core — lihat Getting Started):

• Buttons: Button, ActionIcon, FileButton, CloseButton
• Inputs: TextInput, NumberInput, PasswordInput, Textarea, Select, NativeSelect, MultiSelect, TagsInput, FileInput, Checkbox, Radio, Switch, SegmentedControl, DatePickerInput†, Dropzone†, RichTextEditor†
• Navigation: Anchor, Breadcrumbs, NavLink, Burger, Menu, Tabs, Pagination, Stepper
• Feedback: Alert, Progress, RingProgress, Loader, LoadingOverlay, Skeleton, EmptyState, Notification, NotificationsSystem†
• Overlays: Modal, Tooltip
• Data display: Card, Badge, Avatar, ThemeIcon, Indicator, Paper, Table, DataTable, ColorSwatch, Pill
• Miscellaneous: Divider, VisuallyHidden, Carousel†
• Charts: BarChart†, DonutChart†
• Layout: AppShell + Primitives (primitives.ts: Group, Stack, Flex, Grid, SimpleGrid, Container, Center, Box, Image, ScrollArea, Text, Title)
• Foundations: Colors, Typography, Spacing, Shadows, Radius, Icons (Tabler + preview props)

Visual di-tuning ke Kelola: tombol/input pill + bold, badge pill uppercase, avatar bulat, kartu radius md, font Avenir → Open Sans. Pola komposit list-page (filter + cari + urut + halaman) tersedia lewat DataTable (logika @tanstack/react-table, tampilan tetap Table Prodigy).

Cara pakai:

import '@mantine/core/styles.css';
import { MantineProvider } from '@mantine/core';
import { theme, Button, Badge } from '@talentlytica/prodigy'; // theme = Kelola
// atau eksplisit: import { kelolaTheme } from '@talentlytica/prodigy';

export function App() {
  return (
    <MantineProvider theme={theme}>
      <Button>Simpan</Button>                {/* primary (biru Kelola) */}
      <Button color="secondary">Tambah</Button>
      <Badge color="success">Selesai</Badge>
    </MantineProvider>
  );
}

Pakai sebagai package (di app lain)

Di-publish publik ke npm (npmjs.org) sebagai @talentlytica/prodigy — tanpa token, tanpa setup registry.

1. Install — satu package; pnpm (v8+) & npm (v7+) menarik peer-nya (Mantine + React) otomatis:

pnpm add @talentlytica/prodigy

Pakai yarn / auto-install peers off? sebutkan peer-nya: pnpm add @talentlytica/prodigy @mantine/core @mantine/hooks react react-dom.

2. Pakai — import CSS Mantine + bungkus MantineProvider dengan tema Kelola (lihat contoh di atas).

Font: tema memakai Avenir → fallback Open Sans. Muat font pilihanmu di app konsumen (mis. @fontsource/open-sans, atau <link> Google Fonts); tanpa itu browser jatuh ke sans-serif sistem.

Komponen "berat" (chart, date picker, dropzone, carousel, notifikasi, rich text) di-import dari subpath tersendiri (bukan barrel utama) supaya app yang tak memakainya tak menanggung recharts/tiptap/dll — mis. import { BarChart } from '@talentlytica/prodigy/charts', lalu install peer + CSS-nya (pnpm add @mantine/charts recharts → import '@mantine/charts/styles.css'). Daftar lengkap "komponen → subpath + peer" ada di Storybook Components & Imports (ringkas juga di Getting Started §5).

Rilis versi baru (maintainer): lihat RELEASING.md.

Menambah komponen baru (tanpa fragmentasi)

1. Buat src/components/<Nama>/<Nama>.tsx → export { X, type XProps } from '@mantine/core'; + JSDoc konvensi pakainya.
2. Tambahkan default visual (jika perlu) di src/themes/kelola.ts via X.extend({ defaultProps }).
3. Daftarkan export-nya. Komponen ringan (hanya butuh @mantine/core): tambah di src/components/index.ts (barrel utama). Komponen berat (butuh peer ekstensi seperti @mantine/charts/dates/tiptap/dll): JANGAN di barrel — buat/tambah di file entry subpath (src/<subpath>.ts), lalu daftarkan subpath itu di vite.lib.config.ts (build.lib.entry), package.json (exports + typesVersions), dan tambahkan peer-nya ke peerDependencies (+peerDependenciesMeta.optional) & rollupOptions.external. Lihat src/charts.ts sebagai contoh.
4. Buat <Nama>.stories.tsx (title sesuai kategori kontekstual Mantine, mis. Buttons/… / Inputs/… / Navigation/… — lihat daftar di atas —, argTypes mengikuti props Mantine — tanpa tags: ['autodocs']).
5. Buat halaman docs <Nama>.mdx gaya Gamut (attach via <Meta of={…Stories} />; embed story lewat <Canvas of> + <Controls of>), seperti komponen lain.

Catatan versi

Package manager pnpm (packageManager: [email protected]). Library dibundel Vite lib (ESM) + declarations via tsc (tsconfig.build.json); peer (react, react-dom, @mantine/core) di-externalize. Di-pin ke Mantine ^9.4, Storybook ^10.5, React 19, Vite 8, TypeScript ^5.7. Butuh Node ≥ 20.19 / 22.12. ESLint tidak ikut ter-install secara default — tambahkan saat mengaktifkan lint guard.

Belum termasuk

Komponen Mantine tanpa padanan nyata di audit Integro/Kelola (color picker, rating, slider, tree, dll.) — daftar lengkap + alasannya di design-system.md §4. Bisa ditinjau ulang kalau muncul kebutuhan baru.