@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.
Files changed (2) hide show
  1. package/README.md +357 -4
  2. 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
- User reputation/karma badge with score, level chip, and earned-badges shelf
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
- npm install @molecule/app-reputation-badge-vue
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
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
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
- License: Apache-2.0
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": "0.0.1-stage",
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.4.0",
57
- "@molecule/app-ui-vue": "1.1.5",
58
- "@molecule/app-vue": "3.7.2",
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",