@corepunk/stats

Cross‑framework Corepunk stat rendering toolkit: icon font + metadata + HTML renderer + Vue plugin + global script. Batteries included.

Includes: icon font, stat map, HTML helpers, text replacement, themes, typings, multi‑format builds.

✨ Features

• Universal: plain HTML (global/IIFE), ES modules, UMD, Vue plugin.
• Zero setup global include → CorepunkStats + $stat() + $statText() + $cpStatReplace().
• Vue plugin: <CpStat code="ap"/>, v-cpstat, $cpStat(), $cpStatReplace().
• Text replacement: transform Gain [ap] and [mregen] into fully rendered HTML.
• Runtime extensible: add / override stats dynamically.
• Optional String prototype sugar ('ap'.$stat()).
• Theming helpers (dark / light) + inline color styling.
• TypeScript definitions.
• One CSS (corepunk-stats.css) + optional theme override files.
• Auto style + @font-face injection for the global script (no manual link tag).

📦 1. Installation (Module / Bundler)

npm i @corepunk/stats

Peer dependency: vue@^3 (only if using the Vue plugin).

import { createApp } from 'vue'
import CorepunkStats from '@corepunk/stats'
import '@corepunk/stats/dist/corepunk-stats.css'

createApp(App).use(CorepunkStats).mount('#app')

Template examples:

<CpStat code="ap" />
<span v-cpstat="'sp'"></span>
<span v-html="$cpStat('armor')" />
<!-- Replace inline text tokens -->
<div v-html="$cpStatReplace('Gain [ap] and [mregen]!')"></div>

Composition example:

import { useCorepunkStats } from '@corepunk/stats'
const { stats, getStat, renderStat } = useCorepunkStats()

Token replacement (module):

import { replaceInText } from '@corepunk/stats'
const html = replaceInText('Gain [ap] and [mregen]!')

🌐 2. Standalone Script (No Build Tools)

Drop one script. It auto injects an @font-face + base styles; no extra CSS tag needed.

<script>window.CorepunkStatsConfig = { extendString:true };</script>
<script src="/js/corepunk-stats.global.js"></script>
<script>
	// icon + label HTML
	document.body.insertAdjacentHTML('beforeend', $stat('ap'))
	// name only
	console.log($statText('ap'))
	// String extension (because extendString:true)
	console.log('sp'.$stat())
	// Replace tokens inside arbitrary text
	document.body.insertAdjacentHTML('beforeend', $cpStatReplace('Gain [ap] and [mregen]!'))
</script>

Exports (after load):

• window.CorepunkStats – API
• window.$stat(code) – HTML string
• window.$statText(code) – raw name
• window.$cpStatReplace(text) – token replacement

ES module (tree‑shake) import (bundlers):

import { render, getStat } from '@corepunk/stats/standalone'
const html = render('ap')

UMD usage (AMD/CommonJS loaders) uses corepunk-stats.umd.js.

🧩 3. API Surface

All environments (global or import) share these: | Function | Description | |----------|-------------| | init(options) | Reconfigure + (re)inject styles. Returns API. | | render(code, { trailing?, wrapSpan? }) | Returns HTML with icon + name. | | text(code) | Returns stat display name. | | getStat(code) | Returns raw stat object or null. | | addStats(list) | Add / override stats at runtime. | | injectStyles() | Inject styles if not already. | | extendString() | Add . $stat() & . $statText() to String.prototype. | | options() | Current resolved options. | | replaceInText(text, { trailingMap? }) | Replace [code] tokens with rendered HTML |

Stat object shape:

interface CorepunkStat {
	key: string
	shortcut: string
	name: string
	color?: string | null
	group?: string
	filter?: string | null
}

Init options:

interface CorepunkStatsOptions {
	autoInjectStyles?: boolean   // default true
	extendString?: boolean       // default false
	globalFunctions?: boolean    // default true (adds $stat / $statText)
	classPrefix?: string         // default 'cps-'
	wrapperClass?: string        // default 'cp-stat'
	addStats?: Partial<CorepunkStat>[]
}

🎨 4. Theming

Base styles are in corepunk-stats.css.

Optional helper classes (apply to the wrapper span):

<span class="cp-stat theme-dark" v-html="$cpStat('ap')"></span>
<span class="cp-stat theme-light" v-html="$cpStat('sp')"></span>

Or dynamically append theme-dark / theme-light for UI mode switching.

You can author your own theme overrides; each rendered stat uses:

<span class="cp-stat" style="color:#HEX"> <i class="cps-ap"></i><span class="cp-stat-name">Attack Power</span></span>

➕ 5. Runtime Extension

CorepunkStats.addStats([
	{ key: 'my_custom', shortcut: 'myc', text: { en: 'My Custom' }, color: '#ff0' }
])
document.body.insertAdjacentHTML('beforeend', $stat('myc'))

Existing stats (matched by key or shortcut) are merged.

🔄 6. Custom Data Replacement

Bundlers: alias the JSON file to inject different data:

// Vite / Webpack resolve.alias example
resolve: { alias: { '@corepunk/stats/src/stats.json': path.resolve(__dirname,'my-stats.json') } }

OR call addStats after init() to overlay differences.

🧪 7. TypeScript

Ambient globals + API definitions ship with the package. Typical usage:

import { render, getStat } from '@corepunk/stats/standalone'
const html: string = render('ap')

✅ 8. Testing

Simple smoke test script is included:

npm run test

It builds then verifies render('ap') returns expected markup.

⚡ 9. Performance Notes

render() is O(1) map lookups + string concat. You can cache frequent stats or pre-render lists if micro‑optimizing, but typical use is already trivial.

🗺️ 10. Roadmap (Planned)

• Optional localized bundles.
• Dynamic font subset builder.
• CLI to inject new stats safely.

📄 11. License

MIT

💡 Examples

Input → Output name examples (case‑insensitive):

| Token | Name (text) | Example HTML Snippet | |-------|-------------|----------------------| | [ap] | Attack Power | <span class="cp-stat"><i class="cps-ap"></i><span class="cp-stat-name">Attack Power</span></span> | | [mregen] | Mana Regeneration | (renders icon + "Mana Regeneration") | | [sp] | Skill Power | ... | | [armor] | Armor | ... |

Replace inline:

replaceInText('Deal bonus [ap] and restore [mregen] per second.')
// => HTML string with both tokens expanded

Graceful fallback: unknown tokens stay untouched: replaceInText('Gain [notreal]') // => 'Gain [notreal]'.

Override trailing values:

replaceInText('Gain [ap]!', { trailingMap:{ ap:'+15' } })
// attaches +15 after the stat name

🛠 Font Delivery

• Global script auto injects @font-face (no CSS import required) and loads the provided woff2 by filename (keep it beside the script if self-hosting or serve from CDN when published).
• Module / Vue usage: import corepunk-stats.css once; it declares @font-face referencing the font files packaged under assets/fonts/.
• All font formats (woff2, woff, ttf, eot, svg) ship for broad compatibility; modern browsers primarily use woff2.

🔍 Troubleshooting

| Issue | Fix | |-------|-----| | Icons show empty squares | Ensure font files are being served (network tab) – for global build place fonts next to the script. | | Duplicate styles injected | Call init({ autoInjectStyles:false }) and manage CSS manually. | | Want plain text only | Use text(code) or strip tags after render(). |