@damarkuncoro/agnostic-ui-contracts

Kontrak UI untuk seluruh ekosistem Agnostic UI. Paket ini mendefinisikan tipe, konstanta, props, state, a11y, dan guard/validator yang menjadi sumber kebenaran untuk Base, Theme, Skin, serta adapter React/Vue.

Ringkas

• Import via alias: @damarkuncoro/agnostic-ui/contracts
• Ekspor utama: a11y, keyboard, state, ui/button
• Build ke dist (source murni di src)
• Dependency: tidak bergantung ke paket lain (Contract-first)

Instalasi & Import

Monorepo ini sudah memetakan alias ke source:

// Import tipe/kontrak
import {
  type UiButtonProps,
  type UiButtonVariant,
  type UiButtonSize,
} from '@damarkuncoro/agnostic-ui/contracts'

Alias diset di tsconfig.base.json agar IDE dan tooling resolve ke source: tsconfig.base.json:11

API Surface

• a11y
  • Konstanta ARIA/Role dan tipe: A11Y_ROLES, A11Y_ATTRIBUTES
  • Sumber: src/a11y.ts
• keyboard
  • Konstanta tombol: KEYBOARD_KEYS
  • Sumber: src/keyboard.ts
• state
  • Konstanta state UI: UI_STATES
  • Sumber: src/state.ts
• ui/button
  • Tipe dan kontrak tombol: varian, size, props, state, a11y, events, slots, guards, validate
  • Sumber: src/ui/button/* dan indeks src/ui/button/index.ts:1

Contoh Penggunaan

Di Base (logika)

import { assertUiButtonProps, type UiButtonProps } from '@damarkuncoro/agnostic-ui/contracts'

export function resolveUiButtonProps(props: UiButtonProps) {
  assertUiButtonProps(props)
  // gabungkan default + props pengguna
}

Di Skin (visual)

import { type UiButtonVariant, type UiButtonSize } from '@damarkuncoro/agnostic-ui/contracts'

export function getButtonClass(variant?: UiButtonVariant, size?: UiButtonSize) {
  // mapping varian/size → kelas Tailwind
}

Di Adapter React/Vue (komponen)

import { type UiButtonProps } from '@damarkuncoro/agnostic-ui/contracts'

Build

Jalankan build untuk menghasilkan dist:

pnpm --filter @damarkuncoro/agnostic-ui/contracts build

Konfigurasi build:

• packages/agnostic-ui-contracts/package.json → main: dist/index.js, types: dist/index.d.ts
• packages/agnostic-ui-contracts/tsconfig.json → outDir: dist, rootDir: src, declaration: true

Arsitektur & Aturan Dependency

• Contract → ❌ tidak bergantung apa pun
• Theme & Base → bergantung ke Contract
• Skin → bergantung ke Contract + Theme
• Adapter (React/Vue) → menggabungkan Base + Skin (+ Theme bila perlu)

Dengan pola ini, kontrak menjadi pusat stabilitas API, sementara layer lain dapat berevolusi tanpa memecah kesepakatan tipe/props.

Struktur Direktori

packages/agnostic-ui-contracts/
├─ src/
│  ├─ a11y.ts
│  ├─ keyboard.ts
│  ├─ state.ts
│  └─ ui/
│     └─ button/
│        ├─ ui-button.types.ts
│        ├─ ui-button.contract.ts
│        ├─ ui-button.props.ts
│        ├─ ui-button.state.ts
│        ├─ ui-button.a11y.ts
│        ├─ ui-button.events.ts
│        ├─ ui-button.slots.ts
│        ├─ ui-button.constants.ts
│        ├─ ui-button.guards.ts
│        ├─ ui-button.validate.ts
│        └─ index.ts
└─ dist/ (hasil build)

Catatan

• Entry ekspor paket: packages/agnostic-ui-contracts/src/index.ts mengekspor seluruh modul inti.
• Gunakan alias @damarkuncoro/agnostic-ui/contracts di seluruh paket agar konsisten dan aman terhadap perubahan internal.