<Button as="a" href="/settings">
  Settings
</Button>

<Text as="label" htmlFor="email">
  Email
</Text>

<Box as="section" aria-labelledby="case-title">
  ...
</Box>

Polymorphism is useful only when the visual abstraction and semantic element can vary independently.

<Button>Save</Button>

<a href="/billing">Billing</a>

<button onClick={() => navigate('/billing')}>Billing</button>

Browser tidak melihat ini sebagai link.
User tidak bisa open in new tab.
Screen reader mendapatkan semantic action, bukan navigation.
Right click link behavior hilang.
SEO/crawler behavior bisa berubah.
Keyboard/browser affordance tidak natural.

visual consistency + semantic correctness

<Button as="a" href="/billing">
  Billing
</Button>

own props       → variant, size, tone, loading, selected
host props      → href, type, disabled, htmlFor, aria-*, onClick
merge behavior  → class merge, event compose, ref pass-through

type ButtonOwnProps = {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean
}

Good candidates:
- Text / Typography
- Box / Stack / Flex layout primitive
- Button-like Action component
- Link-like navigational primitive
- Visually styled primitive yang semantic host-nya valid berubah
- Headless trigger/item component yang perlu host berbeda

<Text as="p">Description</Text>
<Text as="span">Inline label</Text>
<Text as="legend">Shipping address</Text>

<Box as="main">...</Box>
<Box as="aside">...</Box>
<Box as="form" onSubmit={handleSubmit}>...</Box>

Poor candidates:
- Checkbox
- RadioGroup
- Dialog
- Select
- Table
- FormField dengan label/error contract ketat
- Domain component seperti CaseApprovalPanel

variant → how it looks
as      → what it is semantically/rendered as

<Button variant="primary">Save</Button>
<Button variant="ghost">Cancel</Button>
<Button as="a" href="/settings" variant="primary">Settings</Button>

<Button variant="link" onClick={() => navigate('/settings')}>
  Settings
</Button>

<Button as="div" onClick={submitForm}>Submit</Button>

Tidak otomatis focusable.
Tidak punya keyboard activation default.
Tidak ikut form submit behavior.
Tidak punya disabled semantics.
Harus reimplement role, tabIndex, keydown.
Screen reader behavior bisa salah.

Do not replace native semantics with ARIA unless you have to.
Prefer native element first.

// Better
<Button type="submit">Submit</Button>

// Avoid unless building custom widget with complete semantics
<Button as="div" role="button" tabIndex={0}>Submit</Button>

<Action href="/cases/123">Open case</Action>
<Action onPress={approveCase}>Approve</Action>

function Action(props: ActionProps) {
  if ('href' in props) {
    return <a className="action" {...props} />
  }

  return <button type="button" className="action" {...props} />
}

type BoxProps = {
  as?: React.ElementType
  className?: string
  children?: React.ReactNode
}

function Box({ as: Comp = 'div', className, ...props }: BoxProps) {
  return <Comp className={className} {...props} />
}

Tidak type-safe untuk host props.
Tidak type-safe untuk ref.
Own props bisa conflict dengan host props.
Semua element diizinkan.
Semantics tidak dibatasi.

<Text as="label" htmlFor="email">Email</Text>
<Text as="a" href="/terms">Terms</Text>
<Text as="button" type="button" onClick={open}>Open</Text>

<Text as="label" href="/terms">Invalid</Text>
<Text as="a" htmlFor="email">Invalid</Text>

type ElementType = React.ElementType

type PropsOf<C extends ElementType> = React.ComponentPropsWithoutRef<C>

type PolymorphicProps<C extends ElementType, OwnProps = {}> =
  OwnProps &
  { as?: C } &
  Omit<PropsOf<C>, keyof OwnProps | 'as'>

type TextOwnProps = {
  tone?: 'default' | 'muted' | 'danger'
  weight?: 'regular' | 'medium' | 'bold'
}

type TextProps<C extends React.ElementType = 'span'> =
  PolymorphicProps<C, TextOwnProps>

function Text<C extends React.ElementType = 'span'>({
  as,
  tone = 'default',
  weight = 'regular',
  className,
  ...props
}: TextProps<C>) {
  const Comp = as ?? 'span'

  return (
    <Comp
      className={cx(
        'text',
        `text--tone-${tone}`,
        `text--weight-${weight}`,
        className,
      )}
      {...props}
    />
  )
}

type OwnProps = {
  size?: 'sm' | 'md' | 'lg'
}

size       → design token vs native input/select size
color      → design token vs old HTML color attr
as         → polymorphic host vs library-specific prop
onChange   → form value change vs custom value change
ref        → host node ref vs imperative API ref
children   → free children vs structured children contract

Own props win.
Host props are allowed after removing conflicting keys.
If conflict is semantic, rename own prop.

type ButtonOwnProps = {
  visualSize?: 'sm' | 'md' | 'lg'
  tone?: 'primary' | 'danger' | 'neutral'
}

For narrow components: size is fine.
For wide polymorphic primitives: prefer visualSize or component-specific naming.

type PolymorphicRef<C extends React.ElementType> =
  React.ComponentPropsWithRef<C>['ref']

type PropsOfWithRef<C extends React.ElementType> =
  React.ComponentPropsWithRef<C>

type PolymorphicPropsWithRef<C extends React.ElementType, OwnProps = {}> =
  OwnProps &
  { as?: C; ref?: PolymorphicRef<C> } &
  Omit<PropsOfWithRef<C>, keyof OwnProps | 'as' | 'ref'>

type TextProps<C extends React.ElementType = 'span'> =
  PolymorphicPropsWithRef<C, TextOwnProps>

function Text<C extends React.ElementType = 'span'>({
  as,
  ref,
  className,
  tone = 'default',
  ...props
}: TextProps<C>) {
  const Comp = as ?? 'span'

  return (
    <Comp
      ref={ref}
      className={cx('text', `text--${tone}`, className)}
      {...props}
    />
  )
}

ref harus menuju host/component yang benar.
Jangan expose internal wrapper ref jika caller mengharapkan semantic host ref.

function Button({ ref, ...props }: ButtonProps<'button'>) {
  return (
    <span className="button-wrapper">
      <button ref={ref} {...props} />
    </span>
  )
}

type PolymorphicComponent = <C extends React.ElementType = 'span'>(
  props: TextProps<C> & { ref?: PolymorphicRef<C> }
) => React.ReactElement | null

const Text = React.forwardRef(function TextInner<C extends React.ElementType = 'span'>(
  { as, className, tone = 'default', ...props }: TextProps<C>,
  ref?: PolymorphicRef<C>,
) {
  const Comp = as ?? 'span'

  return (
    <Comp
      ref={ref}
      className={cx('text', `text--${tone}`, className)}
      {...props}
    />
  )
}) as PolymorphicComponent

forwardRef polymorphic typing is verbose.
Type inference can degrade if terlalu abstrak.
Library authors sering butuh assertion.
Application code sebaiknya tidak terlalu sering menulis pattern ini sendiri.

span, p, label, strong, em, small, div

type TextElement = 'span' | 'p' | 'label' | 'strong' | 'em' | 'small' | 'div'

type TextProps<C extends TextElement = 'span'> =
  PolymorphicPropsWithRef<C, TextOwnProps>

function Text<C extends TextElement = 'span'>(props: TextProps<C>) {
  ...
}

API lebih kecil.
Semantic lebih defensible.
Autocomplete lebih berguna.
Failure mode berkurang.

Caller kadang butuh host yang belum dipikirkan.
Design system perlu update untuk kasus baru.

A component API should make invalid composition hard, not just documented as discouraged.

<Button as={NavLink} to="/cases">
  Cases
</Button>

NavLink mungkin tidak meneruskan className.
NavLink mungkin tidak meneruskan ref.
NavLink mungkin memakai prop `to`, bukan `href`.
NavLink mungkin render anchor tetapi menambah state sendiri.

It must accept className.
It should pass ref to the interactive/semantic host when needed.
It should preserve accessibility props.
It should preserve data-* attributes.
It should not swallow event handlers unexpectedly.

type RouterLinkAdapterProps = React.ComponentPropsWithoutRef<'a'> & {
  to: string
}

const RouterLinkAdapter = React.forwardRef<HTMLAnchorElement, RouterLinkAdapterProps>(
  function RouterLinkAdapter({ to, ...anchorProps }, ref) {
    return <RouterLink ref={ref} to={to} {...anchorProps} />
  },
)

return <Comp {...props} className={computedClassName} />

const mergedClassName = cx(baseClassName, variantClassName, className)

return <Comp {...props} className={mergedClassName} />

return (
  <Comp
    {...props}
    data-ui="button"
    className={mergedClassName}
  />
)

Internal invariant props after spread.
Caller extension props before spread.
Merged props explicit.

<Comp
  {...props}
  role={requiredRole}
  aria-disabled={computedAriaDisabled}
  className={mergedClassName}
/>

function MenuTrigger({ onClick, ...props }) {
  return <button onClick={toggleOpen} {...props} />
}

function composeEventHandlers<E>(
  theirHandler?: (event: E) => void,
  ourHandler?: (event: E) => void,
  options: { checkDefaultPrevented?: boolean } = { checkDefaultPrevented: true },
) {
  return (event: E & { defaultPrevented?: boolean }) => {
    theirHandler?.(event)

    if (options.checkDefaultPrevented === false || !event.defaultPrevented) {
      ourHandler?.(event)
    }
  }
}

<Comp
  {...props}
  onClick={composeEventHandlers(props.onClick, event => {
    setOpen(value => !value)
  })}
/>

Caller may want to prevent default component behavior.

<Menu.Trigger
  onClick={event => {
    if (isReadOnly) event.preventDefault()
  }}
/>

<Button as="a" href="/danger" disabled>
  Delete
</Button>

type AnchorButtonProps = {
  as: 'a'
  href: string
  disabled?: never
}

<a
  aria-disabled={disabled ? true : undefined}
  onClick={disabled ? preventNavigation : onClick}
/>

aria-disabled announces disabled state but does not block behavior.
You must prevent activation yourself.
You must decide whether element remains focusable.

<Button disabled>Save</Button>
<LinkButton href="/settings">Settings</LinkButton>

type ActionProps =
  | ({ href: string; disabled?: never } & AnchorProps)
  | ({ onPress: () => void; disabled?: boolean } & ButtonProps)

<Button loading>Save</Button>

<button disabled={loading || disabled} aria-busy={loading || undefined}>
  {loading && <Spinner />}
  Save
</button>

There is no native disabled anchor.

1. Do not support loading for anchor-like host.
2. Support aria-busy only, navigation tetap jalan.
3. Prevent navigation while loading.
4. Split component: Button vs LinkButton.

If a prop changes interaction semantics, make sure it is valid for every allowed host.

<Button asChild>
  <a href="/settings">Settings</a>
</Button>

as      → component chooses host from prop
asChild → caller provides host element; component decorates it

function Slot({ children, ...slotProps }: SlotProps) {
  if (!React.isValidElement(children)) {
    throw new Error('Slot expects a single React element child.')
  }

  return React.cloneElement(children, mergeProps(slotProps, children.props))
}

function Button({ asChild, className, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : 'button'

  return (
    <Comp
      className={cx('button', className)}
      {...props}
    />
  )
}

Works with framework router components.
Caller fully controls host.
Avoids generic `as={Component}` typing complexity.
Good for headless/design-system primitives.

cloneElement can obscure data flow.
Only one child allowed.
Child must accept injected props.
Event/ref/class merging must be correct.
Type safety weaker.

<Button asChild>
  <RouterLink to="/billing">Billing</RouterLink>
</Button>

className
onClick
data-*
aria-*
ref

function RouterLink({ to, children }: RouterLinkProps) {
  return <a href={to}>{children}</a>
}

type RouterLinkProps = React.ComponentPropsWithoutRef<'a'> & {
  to: string
}

const RouterLink = React.forwardRef<HTMLAnchorElement, RouterLinkProps>(
  function RouterLink({ to, ...props }, ref) {
    return <a ref={ref} href={to} {...props} />
  },
)

function mergeProps(slotProps: AnyProps, childProps: AnyProps) {
  const result = { ...slotProps, ...childProps }

  for (const key in childProps) {
    const slotValue = slotProps[key]
    const childValue = childProps[key]

    if (/^on[A-Z]/.test(key) && typeof slotValue === 'function' && typeof childValue === 'function') {
      result[key] = composeEventHandlers(childValue, slotValue)
    }

    if (key === 'className') {
      result[key] = cx(slotValue, childValue)
    }

    if (key === 'style') {
      result[key] = { ...slotValue, ...childValue }
    }
  }

  return result
}

Child remains the semantic owner.
Slot contributes behavior/style.
Caller can still prevent default behavior.

function composeRefs<T>(
  ...refs: Array<React.Ref<T> | undefined>
): React.RefCallback<T> {
  return value => {
    for (const ref of refs) {
      if (!ref) continue

      if (typeof ref === 'function') {
        ref(value)
      } else {
        ref.current = value
      }
    }
  }
}

const internalRef = React.useRef<HTMLButtonElement | null>(null)

return (
  <button
    ref={composeRefs(internalRef, externalRef)}
    {...props}
  />
)

<Button ref={buttonRef} />              // HTMLButtonElement
<Button as="a" ref={anchorRef} />      // HTMLAnchorElement

<Heading as="h1" size="xl">Case Detail</Heading>
<Heading as="h2" size="lg">Timeline</Heading>
<Heading as="div" role="heading" aria-level={2}>Timeline</Heading>

Use role=heading only when DOM structure forces it.

<Text as="label" htmlFor="email">Email</Text>

<Button as="a" href="/cases/123">Open case</Button>

<Button type="button" onClick={openModal}>Open modal</Button>

type StackOwnProps = {
  gap?: 'xs' | 'sm' | 'md' | 'lg'
  direction?: 'vertical' | 'horizontal'
  align?: 'start' | 'center' | 'end' | 'stretch'
}

type StackProps<C extends React.ElementType = 'div'> =
  PolymorphicPropsWithRef<C, StackOwnProps>

function Stack<C extends React.ElementType = 'div'>({
  as,
  gap = 'md',
  direction = 'vertical',
  align = 'stretch',
  className,
  ...props
}: StackProps<C>) {
  const Comp = as ?? 'div'

  return (
    <Comp
      className={cx(
        'stack',
        `stack--gap-${gap}`,
        `stack--${direction}`,
        `stack--align-${align}`,
        className,
      )}
      {...props}
    />
  )
}

<Stack as="form" onSubmit={handleSubmit} gap="lg">
  ...
</Stack>

<Stack as="ul" gap="sm">
  {items.map(item => <li key={item.id}>{item.name}</li>)}
</Stack>

If Stack as="ul", children should be li.
If Stack as="dl", children should follow dt/dd structure.

type CommonActionProps = {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
}

type ButtonActionProps = CommonActionProps &
  Omit<React.ComponentPropsWithoutRef<'button'>, keyof CommonActionProps> & {
    kind?: 'button'
    href?: never
  }

type LinkActionProps = CommonActionProps &
  Omit<React.ComponentPropsWithoutRef<'a'>, keyof CommonActionProps> & {
    kind: 'link'
    href: string
    disabled?: never
  }

type ActionProps = ButtonActionProps | LinkActionProps

function Action(props: ActionProps) {
  const { variant = 'primary', size = 'md', className, ...rest } = props
  const classes = cx('action', `action--${variant}`, `action--${size}`, className)

  if (props.kind === 'link') {
    const { kind, ...anchorProps } = rest as LinkActionProps
    return <a className={classes} {...anchorProps} />
  }

  const { kind, type = 'button', ...buttonProps } = rest as ButtonActionProps
  return <button type={type} className={classes} {...buttonProps} />
}

Navigation and action are explicit.
Invalid disabled anchor can be blocked.
Button gets default type="button".
Less semantic ambiguity than Button as="a".

Less open-ended than generic as prop.
Router links need adapter or separate prop.

<form>
  <Button onClick={openHelp}>Help</Button>
</form>

<button type={type ?? 'button'} />

<Button as="a" type="button" href="/settings" />

Accessible name tetap ada.
Keyboard behavior sesuai host.
Focus ring tidak dihilangkan.
Disabled state valid.
aria-* diteruskan.
role tidak dipaksa sembarangan.
Ref menuju focusable/semantic node.

<IconButton as="a" href="/settings">
  <SettingsIcon />
</IconButton>

<IconButton as="a" href="/settings" aria-label="Open settings">
  <SettingsIcon aria-hidden="true" />
</IconButton>

if (process.env.NODE_ENV !== 'production') {
  if (!props['aria-label'] && !props['aria-labelledby']) {
    console.warn('IconButton requires an accessible name.')
  }
}

<Menu.Trigger asChild>
  <Button variant="ghost">Actions</Button>
</Menu.Trigger>

aria-haspopup
aria-expanded
aria-controls
onClick
onKeyDown
ref

Menu state mungkin jalan.
Accessibility semantics hilang.
Focus management rusak.
Keyboard orchestration rusak.

Components used asChild targets must be prop-transparent.
They must forward ref to their semantic host.
They must merge event handlers.
They must not swallow aria/data attributes.

type ButtonProps = React.ComponentPropsWithoutRef<'button'> & {
  variant?: 'primary' | 'secondary'
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  function Button({ variant = 'primary', className, ...props }, ref) {
    return (
      <button
        ref={ref}
        className={cx('button', `button--${variant}`, className)}
        {...props}
      />
    )
  },
)

function Button({ variant, children, onClick }: ButtonProps) {
  return <button className="button" onClick={onClick}>{children}</button>
}

aria-*
data-*
id
role
tabIndex
onKeyDown
onPointerDown
ref

<Box as="button" onClick={save} padding="md" color="danger" />

Fast layout composition.
Reduced CSS boilerplate.
Consistent spacing/token usage.

Semantic responsibility pindah ke caller.
Design intent bisa kabur.
Domain code menjadi penuh visual token.
Box bisa menjadi escape hatch untuk design-system governance.

Box is good at layout.
Box is dangerous as product semantic component.

<Box as="section" padding="lg">
  ...
</Box>

<Box as="button" onClick={approveCase}>Approve</Box>

<Button onClick={approveCase}>Approve</Button>

<CaseStatusBadge as="button" onClick={openAuditTrail} status="escalated" />

<button type="button" onClick={openAuditTrail} className="status-button">
  <CaseStatusBadge status="escalated" />
</button>

<CaseStatusAction status="escalated" onOpenAuditTrail={openAuditTrail} />

Primitive components may be polymorphic.
Domain components should be semantically explicit.

function ResponsiveText(props: TextProps) {
  const isMobile = useMediaQuery('(max-width: 600px)')
  return <Text as={isMobile ? 'span' : 'p'} {...props} />
}

Do not choose semantic host from client-only condition during initial render.
Use CSS for responsive visual changes.
Keep DOM semantics stable.

Creating dynamic components inline can remount subtree.
Passing unstable component to `as` can change element type.
Complex prop merging in huge lists adds cost.
cloneElement in massive trees can add overhead.

<ListItem as={() => <a href="/x" />} />

const CaseLink = React.forwardRef<HTMLAnchorElement, AnchorProps>(...)

<ListItem as={CaseLink} />

Do not create `as` component inline.
Use stable component references.

Does it render the requested host?
Does it pass valid host props?
Does it merge className?
Does it compose event handlers?
Does it forward ref to correct node?
Does it preserve aria/data attributes?
Does it block invalid contracts where possible?
Does it keep semantic behavior for button/link?

it('renders anchor when as=a', () => {
  render(<Button as="a" href="/settings">Settings</Button>)

  const link = screen.getByRole('link', { name: /settings/i })
  expect(link).toHaveAttribute('href', '/settings')
})

it('defaults button type to button', () => {
  render(<Button>Open</Button>)

  expect(screen.getByRole('button', { name: /open/i })).toHaveAttribute('type', 'button')
})

it('lets caller prevent internal behavior', async () => {
  const user = userEvent.setup()

  render(
    <Toggle
      onClick={event => event.preventDefault()}
    />,
  )

  await user.click(screen.getByRole('button'))

  expect(screen.getByRole('button')).toHaveAttribute('aria-pressed', 'false')
})

it('forwards ref to anchor host', () => {
  const ref = React.createRef<HTMLAnchorElement>()

  render(<Button as="a" href="/x" ref={ref}>X</Button>)

  expect(ref.current?.tagName).toBe('A')
})

import * as React from 'react'

function cx(...values: Array<string | false | null | undefined>) {
  return values.filter(Boolean).join(' ')
}

type ElementType = React.ElementType

type PolymorphicRef<C extends ElementType> =
  React.ComponentPropsWithRef<C>['ref']

type PolymorphicProps<C extends ElementType, OwnProps = {}> =
  OwnProps &
  { as?: C; ref?: PolymorphicRef<C> } &
  Omit<React.ComponentPropsWithRef<C>, keyof OwnProps | 'as' | 'ref'>

type TextOwnProps = {
  tone?: 'default' | 'muted' | 'danger'
  weight?: 'regular' | 'medium' | 'bold'
}

type TextProps<C extends ElementType = 'span'> =
  PolymorphicProps<C, TextOwnProps>

export function Text<C extends ElementType = 'span'>({
  as,
  ref,
  tone = 'default',
  weight = 'regular',
  className,
  ...props
}: TextProps<C>) {
  const Comp = as ?? 'span'

  return (
    <Comp
      ref={ref}
      className={cx(
        'text',
        `text--tone-${tone}`,
        `text--weight-${weight}`,
        className,
      )}
      {...props}
    />
  )
}

<Text>Inline note</Text>
<Text as="p">Paragraph</Text>
<Text as="label" htmlFor="email">Email</Text>
<Text as="a" href="/terms">Terms</Text>

Default host span.
Host props inferred from as.
Own props preserved.
className merged.
ref typed by host.

Semantic validation across all use cases.
Runtime accessibility warnings.
Restriction of allowed hosts.
asChild support.

type ButtonHost = 'button' | 'a'

type ButtonOwnProps = {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean
}

type ButtonProps<C extends ButtonHost = 'button'> =
  PolymorphicProps<C, ButtonOwnProps>

export function Button<C extends ButtonHost = 'button'>({
  as,
  ref,
  variant = 'primary',
  size = 'md',
  loading = false,
  className,
  children,
  ...props
}: ButtonProps<C>) {
  const Comp = as ?? 'button'

  const commonProps = {
    ref,
    className: cx('button', `button--${variant}`, `button--${size}`, className),
    'data-loading': loading ? '' : undefined,
  }

  if (Comp === 'button') {
    const buttonProps = props as React.ComponentPropsWithoutRef<'button'>

    return (
      <button
        {...buttonProps}
        {...commonProps}
        type={buttonProps.type ?? 'button'}
        disabled={loading || buttonProps.disabled}
        aria-busy={loading || undefined}
      >
        {loading && <Spinner />}
        {children}
      </button>
    )
  }

  const anchorProps = props as React.ComponentPropsWithoutRef<'a'>

  return (
    <a
      {...anchorProps}
      {...commonProps}
      aria-busy={loading || undefined}
    >
      {loading && <Spinner />}
      {children}
    </a>
  )
}

This is intentionally restricted to button and anchor.
It does not pretend all hosts are valid.
It makes button default type explicit.
It treats anchor loading as busy, not disabled.

type AnyProps = Record<string, any>

type SlotProps = AnyProps & {
  children: React.ReactElement
}

function isEventHandler(key: string, value: unknown) {
  return /^on[A-Z]/.test(key) && typeof value === 'function'
}

function mergeSlotProps(slotProps: AnyProps, childProps: AnyProps) {
  const result = { ...slotProps, ...childProps }

  for (const key of Object.keys(slotProps)) {
    const slotValue = slotProps[key]
    const childValue = childProps[key]

    if (key === 'className') {
      result[key] = cx(slotValue, childValue)
      continue
    }

    if (key === 'style') {
      result[key] = { ...slotValue, ...childValue }
      continue
    }

    if (isEventHandler(key, slotValue) && isEventHandler(key, childValue)) {
      result[key] = composeEventHandlers(childValue, slotValue)
    }
  }

  return result
}

export function Slot({ children, ...slotProps }: SlotProps) {
  if (!React.isValidElement(children)) {
    throw new Error('Slot expects a single React element child.')
  }

  return React.cloneElement(
    children,
    mergeSlotProps(slotProps, children.props),
  )
}

<Button asChild>
  <RouterLink to="/cases/123">Open case</RouterLink>
</Button>

<Button as="div" onClick={submit}>Submit</Button>

<Button type="submit">Submit</Button>

<Text as="label" href="/x">Broken</Text>

Caller calls focus(), but ref points to wrapper div instead of button.

Forward ref to semantic/focusable host.
Use separate internal refs for wrappers.

Internal onClick overrides caller onClick or vice versa.

Compose handlers intentionally.
Allow caller preventDefault to cancel internal behavior when appropriate.

Caller className is swallowed.
Headless injected className is swallowed.

Always merge className explicitly.

Box becomes button, link, form, section, card, modal, menu item, everything.

Use polymorphism at primitive layer only.
Create semantic components for product/domain behavior.

<Button as="a" disabled href="/delete">Delete</Button>

Disallow disabled for anchor or implement explicit aria-disabled + activation blocking with documented behavior.

<Component as={() => <a />} />

Use stable component reference.

Primitive layer can be flexible.
Control layer should be semantically responsible.
Product/domain layer should be explicit.

What host elements are allowed?
Why are they allowed?
Which own props conflict with host props?
Does ref point to expected node for every host?
Are event handlers merged or overridden?
Is className merged?
Are aria/data props preserved?
Does disabled/loading behavior make sense for every host?
Does default button type avoid accidental submit?
Does TypeScript reject invalid host props?
Does SSR render stable host element?
Can this be simpler with separate components?

Use polymorphism sparingly.
Prefer explicit Button, LinkButton, Text, Stack.
Avoid generic `as` on domain components.
Do not build a universal Box that bypasses design-system semantics.

Implement polymorphism once, carefully.
Test prop merge/ref/a11y behavior heavily.
Restrict hosts where possible.
Document semantic expectations.
Provide adapters for router integration.

Prefer asChild when caller owns host.
Require prop-transparent child components.
Use event/ref composition utilities.

as default span
variant: body, caption, code
weight: regular, medium, bold
ref support
className merge
host prop inference

Text as label accepts htmlFor.
Text as a accepts href.
Text default renders span.
ref points to correct host.

h1, h2, h3, h4, h5, h6

<Button onClick={save}>Save</Button>
<LinkButton href="/settings">Settings</LinkButton>

<Button as="a" href="/settings">Settings</Button>

single child enforcement
className merge
style merge
event handler composition
ref composition if needed

<Button asChild>
  <RouterLink to="/cases">Cases</RouterLink>
</Button>

function CardAction({ as: Comp = 'div', onClick, children }) {
  return <Comp className="card-action" onClick={onClick}>{children}</Comp>
}

semantic issues
type issues
keyboard issues
ref issues
prop transparency issues

visual abstraction
semantic host
behavior contract
type contract
accessibility contract

The rendered element still matters.

Primitive components may be polymorphic.
Interactive controls should be semantically disciplined.
Domain components should be explicit.
Polymorphism must preserve props, refs, events, accessibility, and invariants.