# Pokenav

Pokenav is a React route-map navigation trail: circular sprite nodes connected by a dotted,
dashed, or wavy trail. It is client-side UI with no router dependency.

Documentation: https://pokenav.devanshsoni.com/usage
Registry catalog: https://pokenav.devanshsoni.com/r/registry.json

## Choose an installation path

Use npm when the application wants the maintained package:

    npm install pokenav

    import { Pokenav, type NavConfig } from 'pokenav'
    import 'pokenav/styles.css'

Use the shadcn registry when the application wants to own and edit the renderer source:

    npx shadcn@latest add https://pokenav.devanshsoni.com/r/pokenav.json

This installs a self-contained component under the project's configured components alias. Import
`Pokenav` from `@/components/pokenav/Pokenav` (adjust the alias if the project differs). The
registry core item supports `spriteUrl` only and has no `pokenav` package dependency.

For `pokemonId`, install the registry adapter instead:

    npx shadcn@latest add https://pokenav.devanshsoni.com/r/pokenav-pokemon.json

It installs the base component and `pokenav@^0.3.1`; import `Pokenav` from
`@/components/pokenav/pokenav-pokemon`. This deliberately adds the package's catalogue and lazy
sprite-import context. Prefer `spriteUrl` when a custom image or a lightweight build is enough.

## API

    type SpriteSource = string | { src: string }
    type NavPosition = 'left' | 'center' | 'right'
    type NavOrientation = 'vertical' | 'horizontal'
    type DotStyle = 'dotted' | 'dashed' | 'solid'
    type RingStyle = 'solid' | 'pokeball'
    type TrailPath = 'straight' | 'wavy'
    type MatchActive = 'exact' | 'prefix' | ((itemHref: string, activeHref: string) => boolean)

    interface NavItem {
      label: string
      href: string
      pokemonId?: number
      spriteUrl?: SpriteSource
      alt?: string
    }

    interface NavTheme {
      accentColor?: string
      surfaceColor?: string
      ringStyle?: RingStyle
      trailPath?: TrailPath
      dotStyle?: DotStyle
      font?: string
      geometry?: { nodeSize?: number; gap?: number; waveAmplitude?: number }
    }

    interface NavConfig {
      position: NavPosition
      orientation: NavOrientation
      items: NavItem[]
      theme?: NavTheme
      matchActive?: MatchActive
    }

    interface PokenavProps extends NavConfig {
      activeHref?: string
      scrollProgress?: number
      ariaLabel?: string
      className?: string
    }

`activeHref` is supplied by the application (for example, `usePathname()` or a router location).
`scrollProgress` is supplied as a finite 0-1 value. Pokenav does not inspect the route, subscribe
to a router, or read `window.scrollY` itself. `pokemonId` resolves only through
`pokenav/pokemon` or the registry Pokemon adapter. `spriteUrl` always wins when both are set.

Defaults: `accentColor: '#64748b'`, `surfaceColor: 'Canvas'`, `ringStyle: 'solid'`,
`trailPath: 'straight'`, `dotStyle: 'dotted'`, and `font: 'inherit'`.

## Examples

    import { Pokenav, type NavConfig } from 'pokenav'
    import 'pokenav/styles.css'

    const config: NavConfig = {
      position: 'left',
      orientation: 'vertical',
      items: [
        { label: 'Home', href: '/', spriteUrl: '/icons/home.png' },
        { label: 'Work', href: '/work', spriteUrl: '/icons/work.png' },
      ],
      theme: { accentColor: '#f97316', trailPath: 'wavy' },
    }

    <Pokenav {...config} activeHref={pathname} />

    import { Pokenav } from 'pokenav/pokemon'

    <Pokenav
      position="left"
      orientation="vertical"
      items={[{ label: 'Home', href: '/', pokemonId: 133 }]}
    />

The registry source uses plain CSS Modules, not Tailwind. Style it through its documented
`data-pallet*` attributes and `--pallet-*` custom properties; generated CSS-module class names
are not public API.