@molecule/app-reputation-badge-vue 0.0.1-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +357 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,364 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-21T12:47:10.779Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-reputation-badge-vue
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Vue reputation/karma surfaces — `<ReputationBadge>` and `<BadgeShelf>` —
|
|
12
|
+
for forum, discussion-board, and social flagships.
|
|
13
|
+
|
|
14
|
+
`<ReputationBadge score={n} />` renders a compact-formatted score ("1.5k")
|
|
15
|
+
plus a tier chip; the tier derives from `score` via `levelForScore` and
|
|
16
|
+
`DEFAULT_THRESHOLDS` (contributor 100, trusted 500, veteran 2000,
|
|
17
|
+
legend 10000) unless you pass `level` or `thresholds`. `variant` is
|
|
18
|
+
`'compact'` (default) or `'full'`
|
|
19
|
+
(stacked with a "Reputation" caption). `<BadgeShelf badges limit onClick />`
|
|
20
|
+
renders earned-badge icons with a trailing `+N` overflow chip
|
|
21
|
+
(`onClick(null)` signals "expand all").
|
|
22
|
+
|
|
23
|
+
This is the Vue counterpart of `@molecule/app-reputation-badge-react`: same
|
|
24
|
+
exports, same props (React names), same DOM for the same input.
|
|
25
|
+
|
|
26
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
27
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
28
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { createApp, defineComponent, h } from 'vue'
|
|
34
|
+
import { BadgeShelf, ReputationBadge } from '@molecule/app-reputation-badge-vue'
|
|
35
|
+
import type { Badge } from '@molecule/app-reputation-badge-vue'
|
|
36
|
+
|
|
37
|
+
const ProfileHeader = defineComponent({
|
|
38
|
+
props: { score: { type: Number, required: true }, badges: { type: Array, required: true } },
|
|
39
|
+
setup(props) {
|
|
40
|
+
return () =>
|
|
41
|
+
h('div', [
|
|
42
|
+
h(ReputationBadge, { score: props.score, variant: 'full' }),
|
|
43
|
+
h(BadgeShelf, {
|
|
44
|
+
badges: props.badges as Badge[],
|
|
45
|
+
limit: 5,
|
|
46
|
+
onClick: (badge: Badge | null) => console.log(badge),
|
|
47
|
+
}),
|
|
48
|
+
])
|
|
49
|
+
},
|
|
50
|
+
})
|
|
51
|
+
|
|
52
|
+
createApp(ProfileHeader).mount('#app')
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Type
|
|
56
|
+
|
|
57
|
+
`feature`
|
|
58
|
+
|
|
59
|
+
## Installation
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install @molecule/app-reputation-badge-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## API
|
|
66
|
+
|
|
67
|
+
### Interfaces
|
|
68
|
+
|
|
69
|
+
#### `ReputationThresholds`
|
|
70
|
+
|
|
71
|
+
Optional thresholds for deriving a `ReputationLevel` from a numeric score.
|
|
72
|
+
|
|
73
|
+
If a `level` prop isn't passed to `<ReputationBadge>`, the component will
|
|
74
|
+
pick the highest level whose threshold the `score` meets or exceeds.
|
|
75
|
+
|
|
76
|
+
Default thresholds:
|
|
4
77
|
|
|
78
|
+
- `contributor` >= 100
|
|
79
|
+
- `trusted` >= 500
|
|
80
|
+
- `veteran` >= 2000
|
|
81
|
+
- `legend` >= 10000
|
|
82
|
+
- below 100 → `newcomer`
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
interface ReputationThresholds {
|
|
86
|
+
/** Score >= contributor threshold ⇒ `'contributor'`. */
|
|
87
|
+
contributor: number
|
|
88
|
+
/** Score >= trusted threshold ⇒ `'trusted'`. */
|
|
89
|
+
trusted: number
|
|
90
|
+
/** Score >= veteran threshold ⇒ `'veteran'`. */
|
|
91
|
+
veteran: number
|
|
92
|
+
/** Score >= legend threshold ⇒ `'legend'`. */
|
|
93
|
+
legend: number
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
#### `Badge`
|
|
98
|
+
|
|
99
|
+
A single earned badge — one icon on the `<BadgeShelf>` row.
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
interface Badge {
|
|
103
|
+
/** Stable identifier (used as the row key + click payload). */
|
|
104
|
+
id: string
|
|
105
|
+
/** Display name (translated upstream — passed verbatim). */
|
|
106
|
+
name: string
|
|
107
|
+
/** Optional longer description, shown in the native tooltip. */
|
|
108
|
+
description?: string
|
|
109
|
+
/** Icon glyph or short emoji (rendered inline). Mutually exclusive with `iconSrc`. */
|
|
110
|
+
icon?: string
|
|
111
|
+
/** Image URL for the badge icon. */
|
|
112
|
+
iconSrc?: string
|
|
113
|
+
/** ISO date string the badge was earned (passed back via `onClick`). */
|
|
114
|
+
earnedAt?: string
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
#### `ReputationBadgeProps`
|
|
119
|
+
|
|
120
|
+
Props accepted by the `ReputationBadge` component — the same props
|
|
121
|
+
React's `@molecule/app-reputation-badge-react` accepts.
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
interface ReputationBadgeProps {
|
|
125
|
+
/** Numeric reputation / karma score. */
|
|
126
|
+
score: number
|
|
127
|
+
/**
|
|
128
|
+
* Explicit reputation level. If omitted, derived from `score` via
|
|
129
|
+
* `levelForScore` using `thresholds` (or `DEFAULT_THRESHOLDS`).
|
|
130
|
+
*/
|
|
131
|
+
level?: ReputationLevel
|
|
132
|
+
/** Override the default score → level thresholds. */
|
|
133
|
+
thresholds?: ReputationThresholds
|
|
134
|
+
/**
|
|
135
|
+
* Layout variant.
|
|
136
|
+
* - `'compact'` (default) — score number inline with a small level chip.
|
|
137
|
+
* - `'full'` — stacked layout with a "Reputation" caption above the row.
|
|
138
|
+
*/
|
|
139
|
+
variant?: 'compact' | 'full'
|
|
140
|
+
/** Extra classes merged onto the outer wrapper. */
|
|
141
|
+
className?: string
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
#### `BadgeShelfProps`
|
|
146
|
+
|
|
147
|
+
Props accepted by the `BadgeShelf` component — the same props React's
|
|
148
|
+
`@molecule/app-reputation-badge-react` accepts.
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
interface BadgeShelfProps {
|
|
152
|
+
/** Earned badges to display, ordered most-prominent-first. */
|
|
153
|
+
badges: Badge[]
|
|
154
|
+
/**
|
|
155
|
+
* Maximum number of badge icons rendered inline. Any remaining are
|
|
156
|
+
* summarised in a trailing `+N` overflow chip.
|
|
157
|
+
*
|
|
158
|
+
* @default 5
|
|
159
|
+
*/
|
|
160
|
+
limit?: number
|
|
161
|
+
/**
|
|
162
|
+
* Click handler — invoked with the clicked badge (or `null` when the
|
|
163
|
+
* trailing overflow chip is clicked, signalling "expand all").
|
|
164
|
+
*/
|
|
165
|
+
onClick?: (badge: Badge | null) => void
|
|
166
|
+
/** Extra classes merged onto the outer row. */
|
|
167
|
+
className?: string
|
|
168
|
+
}
|
|
5
169
|
```
|
|
6
|
-
|
|
170
|
+
|
|
171
|
+
### Types
|
|
172
|
+
|
|
173
|
+
#### `ReputationLevel`
|
|
174
|
+
|
|
175
|
+
Reputation level identifiers — used to pick a tier color/label.
|
|
176
|
+
|
|
177
|
+
Apps that need finer granularity can pass a `level` string of any value;
|
|
178
|
+
unknown values fall back to `'newcomer'` styling.
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
type ReputationLevel = 'newcomer' | 'contributor' | 'trusted' | 'veteran' | 'legend'
|
|
7
182
|
```
|
|
8
183
|
|
|
9
|
-
|
|
184
|
+
### Functions
|
|
185
|
+
|
|
186
|
+
#### `levelForScore(score, thresholds)`
|
|
187
|
+
|
|
188
|
+
Derive a {@link ReputationLevel} from a numeric score.
|
|
189
|
+
|
|
190
|
+
Picks the highest level whose threshold is met or exceeded. Any score
|
|
191
|
+
below `thresholds.contributor` returns `'newcomer'`.
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
function levelForScore(score: number, thresholds?: ReputationThresholds): ReputationLevel
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- `score` — Reputation score (any non-negative number).
|
|
198
|
+
- `thresholds` — Optional override thresholds; defaults to {@link DEFAULT_THRESHOLDS}.
|
|
199
|
+
|
|
200
|
+
**Returns:** The derived reputation level.
|
|
201
|
+
|
|
202
|
+
#### `colorForLevel(level)`
|
|
203
|
+
|
|
204
|
+
Return the semantic Badge color for a given level.
|
|
205
|
+
|
|
206
|
+
Unknown levels fall back to `'secondary'`.
|
|
207
|
+
|
|
208
|
+
```typescript
|
|
209
|
+
function colorForLevel(
|
|
210
|
+
level: ReputationLevel,
|
|
211
|
+
): 'primary' | 'secondary' | 'success' | 'warning' | 'info'
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- `level` — The reputation level.
|
|
215
|
+
|
|
216
|
+
**Returns:** A badge color name from `@molecule/app-ui-vue`.
|
|
217
|
+
|
|
218
|
+
### Constants
|
|
219
|
+
|
|
220
|
+
#### `BadgeShelf`
|
|
221
|
+
|
|
222
|
+
Horizontal row of small badge icons earned by a user — used alongside
|
|
223
|
+
`<ReputationBadge>` to surface community achievements on profile headers,
|
|
224
|
+
post bylines, and detail pages.
|
|
225
|
+
|
|
226
|
+
Each icon shows its name in a native `title` tooltip for low-friction
|
|
227
|
+
accessibility. Clicking a badge invokes `onClick(badge)`; clicking the
|
|
228
|
+
trailing `+N` chip invokes `onClick(null)` so the host page can expand a
|
|
229
|
+
full list.
|
|
230
|
+
|
|
231
|
+
```typescript
|
|
232
|
+
const BadgeShelf: DefineComponent<
|
|
233
|
+
ExtractPropTypes<{
|
|
234
|
+
badges: { type: PropType<Badge[]>; required: true }
|
|
235
|
+
limit: NumberConstructor
|
|
236
|
+
onClick: { type: PropType<((badge: Badge | null) => void) | undefined>; default: undefined }
|
|
237
|
+
className: StringConstructor
|
|
238
|
+
}>,
|
|
239
|
+
() => VNode | null,
|
|
240
|
+
{},
|
|
241
|
+
{},
|
|
242
|
+
{},
|
|
243
|
+
ComponentOptionsMixin,
|
|
244
|
+
ComponentOptionsMixin,
|
|
245
|
+
{},
|
|
246
|
+
string,
|
|
247
|
+
PublicProps,
|
|
248
|
+
Readonly<
|
|
249
|
+
ExtractPropTypes<{
|
|
250
|
+
badges: { type: PropType<Badge[]>; required: true }
|
|
251
|
+
limit: NumberConstructor
|
|
252
|
+
onClick: { type: PropType<((badge: Badge | null) => void) | undefined>; default: undefined }
|
|
253
|
+
className: StringConstructor
|
|
254
|
+
}>
|
|
255
|
+
> &
|
|
256
|
+
Readonly<{}>,
|
|
257
|
+
{ onClick: ((badge: Badge | null) => void) | undefined },
|
|
258
|
+
{},
|
|
259
|
+
{},
|
|
260
|
+
{},
|
|
261
|
+
string,
|
|
262
|
+
ComponentProvideOptions,
|
|
263
|
+
true,
|
|
264
|
+
{},
|
|
265
|
+
any
|
|
266
|
+
>
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
- `props` — Component props (see `BadgeShelfProps`).
|
|
270
|
+
|
|
271
|
+
**Returns:** The rendered shelf, or `null` if no badges are supplied.
|
|
272
|
+
|
|
273
|
+
#### `ReputationBadge`
|
|
274
|
+
|
|
275
|
+
User reputation / karma display.
|
|
276
|
+
|
|
277
|
+
Renders a numeric score paired with a tier chip whose color reflects the
|
|
278
|
+
derived (or explicit) `level`. Tier color comes from the active ClassMap
|
|
279
|
+
bond's `cm.badge()` helper, so apps swapping styling libraries restyle these
|
|
280
|
+
chips for free.
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
const ReputationBadge: DefineComponent<
|
|
284
|
+
ExtractPropTypes<{
|
|
285
|
+
score: { type: NumberConstructor; required: true }
|
|
286
|
+
level: PropType<ReputationLevel | undefined>
|
|
287
|
+
thresholds: PropType<ReputationThresholds | undefined>
|
|
288
|
+
variant: PropType<'compact' | 'full'>
|
|
289
|
+
className: StringConstructor
|
|
290
|
+
}>,
|
|
291
|
+
() => VNode,
|
|
292
|
+
{},
|
|
293
|
+
{},
|
|
294
|
+
{},
|
|
295
|
+
ComponentOptionsMixin,
|
|
296
|
+
ComponentOptionsMixin,
|
|
297
|
+
{},
|
|
298
|
+
string,
|
|
299
|
+
PublicProps,
|
|
300
|
+
Readonly<
|
|
301
|
+
ExtractPropTypes<{
|
|
302
|
+
score: { type: NumberConstructor; required: true }
|
|
303
|
+
level: PropType<ReputationLevel | undefined>
|
|
304
|
+
thresholds: PropType<ReputationThresholds | undefined>
|
|
305
|
+
variant: PropType<'compact' | 'full'>
|
|
306
|
+
className: StringConstructor
|
|
307
|
+
}>
|
|
308
|
+
> &
|
|
309
|
+
Readonly<{}>,
|
|
310
|
+
{},
|
|
311
|
+
{},
|
|
312
|
+
{},
|
|
313
|
+
{},
|
|
314
|
+
string,
|
|
315
|
+
ComponentProvideOptions,
|
|
316
|
+
true,
|
|
317
|
+
{},
|
|
318
|
+
any
|
|
319
|
+
>
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
- `props` — Component props (see `ReputationBadgeProps`).
|
|
323
|
+
|
|
324
|
+
**Returns:** The rendered reputation badge element.
|
|
325
|
+
|
|
326
|
+
#### `DEFAULT_THRESHOLDS`
|
|
327
|
+
|
|
328
|
+
Default thresholds used when no `thresholds` prop is supplied.
|
|
329
|
+
|
|
330
|
+
```typescript
|
|
331
|
+
const DEFAULT_THRESHOLDS: ReputationThresholds
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
## Injection Notes
|
|
335
|
+
|
|
336
|
+
### Requirements
|
|
337
|
+
|
|
338
|
+
Peer dependencies:
|
|
339
|
+
|
|
340
|
+
- `@molecule/app-ui` ^1.0.1
|
|
341
|
+
- `@molecule/app-ui-vue` ^1.1.0
|
|
342
|
+
- `@molecule/app-vue` ^3.5.0
|
|
343
|
+
- `vue` ^3.4.0
|
|
344
|
+
|
|
345
|
+
### Runtime Dependencies
|
|
346
|
+
|
|
347
|
+
- `@molecule/app-ui`
|
|
348
|
+
- `@molecule/app-ui-vue`
|
|
349
|
+
- `@molecule/app-vue`
|
|
350
|
+
- `vue`
|
|
351
|
+
|
|
352
|
+
- Both components throw unless mounted under `moleculePlugin` with i18n
|
|
353
|
+
(`useTranslation()` needs a provider) and a ClassMap bonded via
|
|
354
|
+
`setClassMap()`.
|
|
355
|
+
- This package exports a `Badge` TYPE (earned-badge data shape) — distinct
|
|
356
|
+
from the `Badge` COMPONENT in `@molecule/app-ui-vue`; alias one when
|
|
357
|
+
importing both in a file.
|
|
358
|
+
- Server-side score/badge issuance pairs with `@molecule/api-reputation`.
|
|
359
|
+
- Translations live in the companion `@molecule/app-locales-reputation-badge`
|
|
360
|
+
bond (registered).
|
|
361
|
+
|
|
362
|
+
## Translations
|
|
10
363
|
|
|
11
|
-
|
|
364
|
+
Translation strings are provided by `@molecule/app-locales-reputation-badge`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-reputation-badge-vue",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "User reputation/karma badge with score, level chip, and earned-badges shelf",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-reputation-badge-vue",
|
|
6
6
|
"type": "module",
|
|
@@ -53,9 +53,9 @@
|
|
|
53
53
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
54
54
|
"@molecule/app-i18n": "1.2.2",
|
|
55
55
|
"@molecule/app-icons": "1.0.4",
|
|
56
|
-
"@molecule/app-ui": "1.
|
|
57
|
-
"@molecule/app-ui-vue": "1.1
|
|
58
|
-
"@molecule/app-vue": "3.
|
|
56
|
+
"@molecule/app-ui": "1.5.0",
|
|
57
|
+
"@molecule/app-ui-vue": "1.2.1",
|
|
58
|
+
"@molecule/app-vue": "3.9.0",
|
|
59
59
|
"@types/node": "26.6.5",
|
|
60
60
|
"jsdom": "30.1.3",
|
|
61
61
|
"typescript": "6.0.3",
|