what props mean
who owns state
when callbacks fire
what DOM semantics are rendered
how accessibility is guaranteed
what is controlled or uncontrolled
what can be composed inside
what is stable across releases
what failure modes are prevented

A reusable component is a public protocol disguised as JSX.

function Modal({ open, children }) {
  if (!open) return null
  return <div className="modal">{children}</div>
}

close on escape
close on backdrop click
prevent close while submitting
focus trap
initial focus
restore focus
aria-labelledby
nested modal prevention
dirty form confirmation
animation lifecycle
portal container

props bertambah tanpa struktur
callback timing tidak konsisten
state ownership ambigu
accessibility rapuh
breaking change tidak terlihat
component sulit dites

<CaseTable
  cases={cases}
  selectedCaseId={selectedCaseId}
  onSelectedCaseChange={setSelectedCaseId}
  onOpenCase={openCase}
/>

cases                         → read model input
selectedCaseId                → controlled selection state
onSelectedCaseChange          → selection transition event
onOpenCase                    → command intent

<CaseTable
  data={cases}
  value={selectedCaseId}
  onChange={setSelectedCaseId}
  onClick={openCase}
/>

Generic names are fine for primitives.
Domain components need domain language.

Data contract says items may be empty.
Rendering contract forgets empty state.
Event contract fires onSelect with stale item.
Accessibility contract forgets selected state.

What data shape is accepted?
Which fields are required?
Can data be empty?
Can data contain duplicate ids?
Can data change order?
Can data be partially loaded?
Does component own sorting/filtering or caller does?

type TableProps = {
  data: any[]
}

type CaseRow = {
  id: CaseId
  referenceNumber: string
  status: CaseStatus
  assigneeName: string | null
  updatedAt: string
}

type CaseTableProps = {
  cases: CaseRow[]
  getCaseId?: (caseRow: CaseRow) => CaseId
  emptyState?: React.ReactNode
}

type DataTableProps<TItem, TId extends string | number> = {
  items: readonly TItem[]
  getItemId: (item: TItem) => TId
  columns: readonly ColumnDef<TItem>[]
  emptyState?: React.ReactNode
}

No identity, no stable selection.
No identity, no stable animation.
No identity, no reliable update reconciliation.

Owned by component
Owned by caller
Derived from props
Stored externally
Owned by server/cache
Owned by URL

<Tabs value={tab} onValueChange={setTab} />

<Tabs defaultValue="activity" />

type TabsProps = {
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
}

If value is provided, component is controlled.
If value is absent, component owns state initialized from defaultValue.
defaultValue is read only on mount.
onValueChange fires before/after internal state update?
Can controlled value be invalid?
What happens if selected tab disappears?

Ownership:
- Controlled when `value` is provided.
- Uncontrolled when `value` is undefined.
- `defaultValue` is only used for initial uncontrolled state.

Transitions:
- User interaction calls `onValueChange(nextValue)`.
- In controlled mode, caller must pass updated `value` to reflect change.
- In uncontrolled mode, component updates internal state after firing callback.

Invalid values:
- If `value` does not match any item, no item is selected.
- The component does not auto-correct controlled value.

Reset:
- Change `key` to reset uncontrolled state.

onClick?: () => void
onChange?: (value: string) => void
onSubmit?: (data: FormData) => void

onClick          → low-level DOM-ish event
onSelect         → user selected item
onValueChange    → value changed
onOpenChange     → open state changed
onRequestClose   → user/system requests close, caller may deny
onConfirm        → user confirmed command
onCommit         → draft committed
onCancel         → user abandoned draft

<Dialog onChange={handleDialogChange} />

open state?
selected item?
form value?
loading state?

<Dialog
  open={open}
  onOpenChange={setOpen}
  onConfirm={submit}
/>

onSelect?: (index: number) => void

Index berubah saat sorting/filtering.
Caller harus lookup item sendiri.
Identity tidak stabil.

onSelect?: (event: {
  id: CaseId
  item: CaseRow
  source: 'mouse' | 'keyboard' | 'programmatic'
}) => void

onValueChange?: (value: string) => void

onDecisionSubmit?: (command: {
  caseId: CaseId
  decision: 'approve' | 'reject' | 'escalate'
  reason?: string
}) => Promise<void> | void

Event callback   → component reports something happened
Command callback → component asks application to do something

onValueChange(nextValue)
onOpenChange(nextOpen)
onSelectionChange(nextSelection)

onSave(command)
onApprove(command)
onNavigate(destination)
onUpload(file)

<ApprovalPanel onChange={approveCase} />

<ApprovalPanel onApprove={approveCase} />

Does component await the promise?
Does component show pending state?
Can user click twice?
What happens on rejection?
Does component catch error or caller handles it?
Can operation be cancelled?
Does successful command close modal automatically?

<ConfirmDialog onConfirm={deleteCase} />

type ConfirmDialogProps = {
  open: boolean
  onOpenChange: (open: boolean) => void
  onConfirm: () => Promise<void> | void
  closeOnConfirm?: boolean
  closeOnConfirmSuccess?: boolean
}

Contract:
- onConfirm may return promise.
- Confirm button enters pending while promise is pending.
- Dialog remains open during pending.
- On success, dialog closes.
- On error, dialog remains open and calls onError.

async function handleConfirm() {
  try {
    setPending(true)
    await onConfirm()
    onOpenChange(false)
  } catch (error) {
    onError?.(error)
  } finally {
    setPending(false)
  }
}

<ConfirmDialog
  pending={deleteMutation.isPending}
  onConfirm={() => deleteMutation.mutate(caseId)}
/>

What DOM role/element is rendered?
Does component render null in some states?
Does it use portal?
Does it preserve children order?
Does it clone children?
Does it add wrappers?
Does ref target host or wrapper?
Does it preserve stable keys?

<Tooltip content="More info">
  <button>Info</button>
</Tooltip>

Tooltip requires exactly one focusable child.
Tooltip may clone child to attach aria-describedby and event handlers.
Tooltip content is rendered in a portal.
Tooltip does not change child semantic role.

<Tooltip content="Info">
  <span>Info</span>
</Tooltip>

What accessible name is required?
What role is rendered?
What keyboard interactions are supported?
How focus is managed?
How disabled/loading/error states are announced?
What aria attributes are caller responsibility?
What aria attributes component owns?

type IconButtonProps = React.ComponentPropsWithoutRef<'button'> & {
  'aria-label': string
  children: React.ReactElement
}

type DialogProps = {
  open: boolean
  onOpenChange: (open: boolean) => void
  title: React.ReactNode
  description?: React.ReactNode
  children: React.ReactNode
}

<Dialog>{children}</Dialog>

What children are allowed?
Is order important?
Can children be arbitrary ReactNode?
Must children be component parts?
Does component use context for descendants?
Can parts be nested?
Can parts be conditional?
Can parts render outside via portal?

<Tabs value={tab} onValueChange={setTab}>
  <Tabs.List>
    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
    <Tabs.Trigger value="history">History</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Panel value="overview">...</Tabs.Panel>
  <Tabs.Panel value="history">...</Tabs.Panel>
</Tabs>

Tabs.Trigger must be rendered under Tabs.
Each Trigger value should be unique.
Each Panel value should correspond to a Trigger.
Tabs.List provides keyboard roving focus among triggers.
Panels can be lazily mounted or always mounted depending prop.

Warn in dev?
Last wins?
First wins?
Throw?

type AlertProps = {
  type?: 'success' | 'error' | 'warning'
  successMessage?: string
  errorMessage?: string
  warningMessage?: string
}

<Alert type="success" errorMessage="Failed" />

type AlertProps =
  | { type: 'success'; message: string; retry?: never }
  | { type: 'error'; message: string; retry?: () => void }
  | { type: 'warning'; message: string; action?: React.ReactNode }

type LoadableViewProps<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'error'; error: Error; onRetry?: () => void }
  | { status: 'success'; data: T }

type Controlled<T> = {
  value: T
  onValueChange: (value: T) => void
  defaultValue?: never
}

type Uncontrolled<T> = {
  value?: never
  onValueChange?: (value: T) => void
  defaultValue?: T
}

type ControllableProps<T> = Controlled<T> | Uncontrolled<T>

type TabsProps = ControllableProps<string> & {
  children: React.ReactNode
}

<Tabs value="overview" />

<Tabs value="overview" />

If value is provided without onValueChange, component is read-only controlled.
User interaction does not change selection.

Duplicate tab values.
Missing accessible name.
Value does not match item.
Child component not under provider.

function invariant(condition: unknown, message: string): asserts condition {
  if (!condition) {
    throw new Error(message)
  }
}

function useTabsContext() {
  const context = React.useContext(TabsContext)

  invariant(
    context,
    'Tabs components must be rendered within <Tabs>.',
  )

  return context
}

if (process.env.NODE_ENV !== 'production') {
  if (values.size !== triggers.length) {
    console.warn('Tabs.Trigger values must be unique.')
  }
}

function SearchBox({ defaultQuery = '' }) {
  const [query, setQuery] = useState(defaultQuery)
}

defaultQuery is used only on initial mount.
Changing defaultQuery later does not reset query.
Use `key` or controlled `query` to reset.

useEffect(() => {
  setQuery(defaultQuery)
}, [defaultQuery])

<SearchBox query={query} onQueryChange={setQuery} />

<SearchBox key={savedSearchId} defaultQuery={savedSearch.query} />

Does ref point to DOM node?
Which DOM node?
Does ref expose imperative handle?
Is ref stable across states?
Can ref be null when closed/unmounted?

<TextInput ref={inputRef} />

inputRef.current.focus()
inputRef.current.select()

type ComboboxHandle = {
  focusInput: () => void
  open: () => void
  close: () => void
}

Imperative API should be minimal and stable.

Can caller pass className?
Where is className applied?
Can caller pass style?
Are data attributes exposed for styling states?
Are CSS variables part of public API?
Can caller override internal layout?

<Button className="my-button" />

Document it.

<button
  data-state={open ? 'open' : 'closed'}
  data-disabled={disabled ? '' : undefined}
/>

.button[data-state='open'] {
  ...
}

<Card
  title="Case summary"
  actions={<Button>Edit</Button>}
/>

<DataTable
  items={cases}
  renderRow={caseRow => <CaseRow case={caseRow} />}
/>

<PageLayout
  sidebar={<CaseFilters />}
  content={<CaseList />}
/>

How often is render function called?
Can it use Hooks? No, if it is callback, not component.
What props does slot receive?
Who owns key?
Who owns layout wrapper?
Can slot return null?

type ListProps<T> = {
  items: readonly T[]
  getItemId: (item: T) => string
  renderItem: (item: T, meta: { selected: boolean }) => React.ReactNode
}

renderItem must be pure.
Do not call Hooks inside renderItem.
If item needs hooks, render a component from renderItem.

<FormField name="email">
  <FormLabel>Email</FormLabel>
  <FormInput />
  <FormError />
</FormField>

FormField provides id/name/error/describedBy to descendants.
FormInput reads field context.
FormLabel reads id and htmlFor.
FormError reads error and id.

<FormInput />

throw helpful error
or support standalone mode explicitly

Primitive component:
- generic props
- visual/behavior focused
- low domain knowledge

Application component:
- knows app services/hooks
- orchestrates data and commands
- composes primitives

Domain component:
- speaks domain language
- enforces business invariants at UI boundary
- does not expose generic low-level knobs unnecessarily

<Button variant="primary" />

<EnforcementDecisionPanel
  caseId={caseId}
  allowedDecisions={allowedDecisions}
  onSubmitDecision={submitDecision}
/>

<Panel data={caseData} actions={actions} renderFooter={...} />

caller misuse
async command failed
data invalid
render child threw
external dependency failed

<Tabs.Trigger value="x" /> // outside Tabs

<ConfirmDialog onConfirm={deleteCase} />

<Select value="missing" options={options} />

render empty selection
warn in dev
throw if invariant impossible

{query.isLoading ? (
  <CaseTableSkeleton />
) : (
  <CaseTable cases={query.data ?? []} />
)}

<CaseTable
  status={query.status}
  cases={query.data ?? []}
  error={query.error}
/>

Does component accept empty array as valid data?
Does empty array mean no result or not loaded yet?
Does loading preserve previous data?
Does error replace table or show inline?

<Button disabled={!canApprove}>Approve</Button>

<PermissionGate
  capability="case.approve"
  fallback={<Button disabled title="You cannot approve this case">Approve</Button>}
>
  <Button onClick={approve}>Approve</Button>
</PermissionGate>

<ApproveCaseButton
  caseId={caseId}
  permission={approvalPermission}
  onApprove={approve}
/>

Hidden or disabled?
Does disabled explain why?
Is unauthorized action still blocked server-side?
Is audit trail affected?
Can user request access?

Can render 10 rows? 1,000 rows? 100,000 rows?
Does it virtualize?
Are row renderers memo-sensitive?
Does selection update rerender all rows?
Are callbacks stable?
Does component preserve row state while sorting?

DataTable is optimized for up to 500 rows without virtualization.
For larger datasets, use VirtualizedDataTable.
getRowId must be stable.
columns should be memoized by caller.

callback fires earlier/later
default prop changes
DOM structure changes
className target changes
role changes
focus behavior changes
controlled/uncontrolled semantics changes
portal container changes

Changing Dialog to close immediately before async onConfirm finishes is breaking.
Changing Button default type from submit to button is breaking for some forms.
Changing className from root to inner element is breaking for styling.

## Purpose
What problem this component solves.

## Ownership
Which state is owned by caller vs component.

## Props
Meaning of non-obvious props.

## Events
When callbacks fire and what payload means.

## Accessibility
Roles, labels, keyboard, focus, aria ownership.

## Composition
Allowed children/slots and structural constraints.

## Async behavior
Pending/error/success contract.

## Styling
className target, data attributes, CSS variables.

## Edge cases
Empty, invalid value, duplicate ids, disabled, loading.

## Examples
Controlled, uncontrolled, error, async, composition.

type ControlledTabsProps = {
  value: string
  onValueChange: (value: string) => void
  defaultValue?: never
}

type UncontrolledTabsProps = {
  value?: never
  defaultValue?: string
  onValueChange?: (value: string) => void
}

type TabsProps = (ControlledTabsProps | UncontrolledTabsProps) & {
  orientation?: 'horizontal' | 'vertical'
  activationMode?: 'automatic' | 'manual'
  children: React.ReactNode
}

function useControllableState<T>({
  value,
  defaultValue,
  onChange,
}: {
  value?: T
  defaultValue: T
  onChange?: (value: T) => void
}) {
  const [internalValue, setInternalValue] = React.useState(defaultValue)
  const controlled = value !== undefined
  const currentValue = controlled ? value : internalValue

  const setValue = React.useCallback((nextValue: T) => {
    onChange?.(nextValue)

    if (!controlled) {
      setInternalValue(nextValue)
    }
  }, [controlled, onChange])

  return [currentValue, setValue, controlled] as const
}

type TabsContextValue = {
  value: string
  setValue: (value: string) => void
  orientation: 'horizontal' | 'vertical'
  activationMode: 'automatic' | 'manual'
}

const TabsContext = React.createContext<TabsContextValue | null>(null)

function useTabsContext(componentName: string) {
  const context = React.useContext(TabsContext)

  if (!context) {
    throw new Error(`${componentName} must be used within <Tabs>.`)
  }

  return context
}

function Tabs({
  value,
  defaultValue = '',
  onValueChange,
  orientation = 'horizontal',
  activationMode = 'automatic',
  children,
}: TabsProps) {
  const [currentValue, setValue] = useControllableState({
    value,
    defaultValue,
    onChange: onValueChange,
  })

  const context = React.useMemo(() => ({
    value: currentValue,
    setValue,
    orientation,
    activationMode,
  }), [currentValue, setValue, orientation, activationMode])

  return (
    <TabsContext.Provider value={context}>
      {children}
    </TabsContext.Provider>
  )
}

type TabsTriggerProps = React.ComponentPropsWithoutRef<'button'> & {
  value: string
}

function TabsTrigger({ value, onClick, ...props }: TabsTriggerProps) {
  const tabs = useTabsContext('Tabs.Trigger')
  const selected = tabs.value === value

  return (
    <button
      {...props}
      type="button"
      role="tab"
      aria-selected={selected}
      data-state={selected ? 'active' : 'inactive'}
      onClick={composeEventHandlers(onClick, () => {
        tabs.setValue(value)
      })}
    />
  )
}

type TabsPanelProps = React.ComponentPropsWithoutRef<'div'> & {
  value: string
  forceMount?: boolean
}

function TabsPanel({ value, forceMount = false, ...props }: TabsPanelProps) {
  const tabs = useTabsContext('Tabs.Panel')
  const selected = tabs.value === value

  if (!selected && !forceMount) return null

  return (
    <div
      {...props}
      role="tabpanel"
      hidden={!selected}
      data-state={selected ? 'active' : 'inactive'}
    />
  )
}

controlled/uncontrolled ownership
context guard
button semantics
role semantics
onValueChange timing
data-state styling
forceMount behavior

ConfirmDialog is controlled by `open`.
`onOpenChange` reports requested open state changes.
`onConfirm` may be async.
While confirm is pending, confirm/cancel controls are disabled.
On success, dialog closes.
On error, dialog remains open and `onError` fires.
Caller may control error rendering via `error` prop.

type ConfirmDialogProps = {
  open: boolean
  onOpenChange: (open: boolean) => void
  title: React.ReactNode
  description?: React.ReactNode
  confirmLabel?: string
  cancelLabel?: string
  onConfirm: () => Promise<void> | void
  onError?: (error: unknown) => void
  children?: React.ReactNode
}

function ConfirmDialog({
  open,
  onOpenChange,
  title,
  description,
  confirmLabel = 'Confirm',
  cancelLabel = 'Cancel',
  onConfirm,
  onError,
  children,
}: ConfirmDialogProps) {
  const [pending, setPending] = React.useState(false)

  async function handleConfirm() {
    try {
      setPending(true)
      await onConfirm()
      onOpenChange(false)
    } catch (error) {
      onError?.(error)
    } finally {
      setPending(false)
    }
  }

  return (
    <Dialog open={open} onOpenChange={pending ? () => {} : onOpenChange}>
      <Dialog.Content aria-busy={pending || undefined}>
        <Dialog.Title>{title}</Dialog.Title>
        {description && <Dialog.Description>{description}</Dialog.Description>}
        {children}
        <Dialog.Footer>
          <Button disabled={pending} onClick={() => onOpenChange(false)}>
            {cancelLabel}
          </Button>
          <Button disabled={pending} onClick={handleConfirm}>
            {pending ? 'Working...' : confirmLabel}
          </Button>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog>
  )
}

<ConfirmDialog
  open={open}
  onOpenChange={setOpen}
  pending={mutation.isPending}
  onConfirm={() => mutation.mutateAsync()}
/>

<Button primary danger outline large loading active />

<Button variant="danger" size="lg" loading />

<Component onChange={handleChange} />

<Component onSelectedCaseChange={handleSelectedCaseChange} />

<Select onValueChange={handleValueChange} />

<Component value={value} defaultValue="x" />

Use controlled or uncontrolled, not both.

<Dialog onConfirm={asyncSave} />

Document and implement async lifecycle.

<Card className="make-it-clickable" onClick={...} />

<CardAction onOpen={...} />

React.Children.map(children, child => {
  if (child.type === CardHeader) ...
})

Use explicit slots or context-based compound components.

function useDialogContext() {
  return React.useContext(DialogContext) ?? defaultDialogContext
}

Throw helpful error unless standalone mode is explicitly supported.

What is this component responsible for?
What is it explicitly not responsible for?
Who owns each piece of state?
Which props are source of truth?
Which props are initial-only?
What callbacks fire, when, and with what payload?
What invalid combinations are impossible by type?
What invalid combinations are guarded at runtime?
What DOM semantics are guaranteed?
What accessibility behavior is guaranteed?
Where does className attach?
Where does ref attach?
Can children be arbitrary?
Can this component be used without provider?
What happens on empty/loading/error states?
What behavior would be breaking if changed later?

<CaseDecisionPanel
  data={caseData}
  status={status}
  onChange={handleChange}
  onSubmit={handleSubmit}
  disabled={disabled}
/>

data too generic
status could mean case status or loading status
onChange ambiguous
disabled does not explain permission/process reason
submit payload unclear
ownership of draft unclear

type CaseDecisionPanelProps = {
  caseId: CaseId
  currentStatus: CaseStatus
  availableDecisions: readonly DecisionOption[]
  permission: DecisionPermission
  defaultDraft?: DecisionDraft
  onDraftChange?: (draft: DecisionDraft) => void
  onSubmitDecision: (command: SubmitDecisionCommand) => Promise<void>
  onCancel?: () => void
}

caseId identifies domain target
currentStatus is read model
availableDecisions constrains valid user choices
permission controls UI affordance
defaultDraft indicates uncontrolled draft initialization
onDraftChange reports draft edits
onSubmitDecision is async command

type ControlledDecisionPanelProps = {
  draft: DecisionDraft
  onDraftChange: (draft: DecisionDraft) => void
}

type UncontrolledDecisionPanelProps = {
  defaultDraft?: DecisionDraft
  onDraftChange?: (draft: DecisionDraft) => void
}

open=true              → enter OpenIdle
onConfirm              → OpenIdle -> Pending
onConfirm success      → Pending -> Closed
onConfirm failure      → Pending -> OpenError
onOpenChange(false)    → OpenIdle/OpenError -> Closed

double confirm
close during pending
lost error
retry after stale command

## ConfirmDialog Contract

### Ownership
`open` is controlled by caller. Internal component owns only transient pending state.

### Events
`onOpenChange(false)` is called when user requests close. It is not called while confirm is pending.

### Async
`onConfirm` may return a promise. While pending, buttons are disabled. On success, dialog closes. On error, dialog stays open and `onError` fires.

### Accessibility
Dialog content has role dialog through underlying Dialog primitive. `title` is required and used as accessible label.

### Composition
`children` render inside dialog body. Footer actions are owned by ConfirmDialog.

### Styling
`className` attaches to dialog content root. State is exposed through `data-pending`.

data shape
state ownership
event meaning
async lifecycle
rendered semantics
accessibility responsibilities
composition rules
styling/ref behavior
invalid states
failure modes
versioning expectations

Every prop is a promise.
Every callback is an event protocol.
Every child slot is a composition contract.
Every rendered DOM node is a semantic commitment.