@molecule/app-reputation-badge-solid 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 +281 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,288 @@
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.261Z
7
+ -->
8
+
1
9
  # @molecule/app-reputation-badge-solid
2
10
 
3
- User reputation/karma badge with score, level chip, and earned-badges shelf
11
+ Solid 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'` (stacked with a "Reputation" caption).
19
+ `<BadgeShelf badges limit onClick />` renders earned-badge icons with a
20
+ trailing `+N` overflow chip (`onClick(null)` signals "expand all").
21
+
22
+ This is the Solid counterpart of `@molecule/app-reputation-badge-react`: same
23
+ exports, same props (React names), same DOM for the same input.
24
+
25
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
26
+ > It is written to be read by coding agents as much as by people, and is generated from this
27
+ > package's source — edit `src/index.ts` JSDoc, not this file.
28
+
29
+ ## Quick Start
30
+
31
+ ```tsx
32
+ import { BadgeShelf, ReputationBadge } from '@molecule/app-reputation-badge-solid'
33
+ import type { Badge } from '@molecule/app-reputation-badge-solid'
34
+
35
+ function ProfileHeader(props: {
36
+ score: number
37
+ badges: Badge[]
38
+ onBadgeClick: (badge: Badge | null) => void
39
+ }) {
40
+ return (
41
+ <div>
42
+ <ReputationBadge score={props.score} variant="full" />
43
+ <BadgeShelf badges={props.badges} limit={5} onClick={props.onBadgeClick} />
44
+ </div>
45
+ )
46
+ }
47
+ ```
48
+
49
+ ## Type
50
+
51
+ `feature`
52
+
53
+ ## Installation
54
+
55
+ ```bash
56
+ npm install @molecule/app-reputation-badge-solid @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
57
+ ```
58
+
59
+ ## API
60
+
61
+ ### Interfaces
62
+
63
+ #### `ReputationThresholds`
64
+
65
+ Optional thresholds for deriving a `ReputationLevel` from a numeric score.
66
+
67
+ If a `level` prop isn't passed to `<ReputationBadge>`, the component will
68
+ pick the highest level whose threshold the `score` meets or exceeds.
69
+
70
+ Default thresholds:
71
+
72
+ - `contributor` >= 100
73
+ - `trusted` >= 500
74
+ - `veteran` >= 2000
75
+ - `legend` >= 10000
76
+ - below 100 → `newcomer`
77
+
78
+ ```typescript
79
+ interface ReputationThresholds {
80
+ /** Score >= contributor threshold ⇒ `'contributor'`. */
81
+ contributor: number
82
+ /** Score >= trusted threshold ⇒ `'trusted'`. */
83
+ trusted: number
84
+ /** Score >= veteran threshold ⇒ `'veteran'`. */
85
+ veteran: number
86
+ /** Score >= legend threshold ⇒ `'legend'`. */
87
+ legend: number
88
+ }
89
+ ```
90
+
91
+ #### `Badge`
92
+
93
+ A single earned badge — one icon on the `<BadgeShelf>` row.
94
+
95
+ ```typescript
96
+ interface Badge {
97
+ /** Stable identifier (used as the row key + click payload). */
98
+ id: string
99
+ /** Display name (translated upstream — passed verbatim). */
100
+ name: string
101
+ /** Optional longer description, shown in the native tooltip. */
102
+ description?: string
103
+ /** Icon glyph or short emoji (rendered inline). Mutually exclusive with `iconSrc`. */
104
+ icon?: string
105
+ /** Image URL for the badge icon. */
106
+ iconSrc?: string
107
+ /** ISO date string the badge was earned (passed back via `onClick`). */
108
+ earnedAt?: string
109
+ }
110
+ ```
111
+
112
+ #### `ReputationBadgeProps`
113
+
114
+ Props accepted by the `ReputationBadge` component — the same props
115
+ React's `@molecule/app-reputation-badge-react` accepts.
116
+
117
+ ```typescript
118
+ interface ReputationBadgeProps {
119
+ /** Numeric reputation / karma score. */
120
+ score: number
121
+ /**
122
+ * Explicit reputation level. If omitted, derived from `score` via
123
+ * `levelForScore` using `thresholds` (or `DEFAULT_THRESHOLDS`).
124
+ */
125
+ level?: ReputationLevel
126
+ /** Override the default score → level thresholds. */
127
+ thresholds?: ReputationThresholds
128
+ /**
129
+ * Layout variant.
130
+ * - `'compact'` (default) — score number inline with a small level chip.
131
+ * - `'full'` — stacked layout with a "Reputation" caption above the row.
132
+ */
133
+ variant?: 'compact' | 'full'
134
+ /** Extra classes merged onto the outer wrapper. */
135
+ className?: string
136
+ }
137
+ ```
138
+
139
+ #### `BadgeShelfProps`
140
+
141
+ Props accepted by the `BadgeShelf` component — the same props React's
142
+ `@molecule/app-reputation-badge-react` accepts.
143
+
144
+ ```typescript
145
+ interface BadgeShelfProps {
146
+ /** Earned badges to display, ordered most-prominent-first. */
147
+ badges: Badge[]
148
+ /**
149
+ * Maximum number of badge icons rendered inline. Any remaining are
150
+ * summarised in a trailing `+N` overflow chip.
151
+ *
152
+ * @default 5
153
+ */
154
+ limit?: number
155
+ /**
156
+ * Click handler — invoked with the clicked badge (or `null` when the
157
+ * trailing overflow chip is clicked, signalling "expand all").
158
+ */
159
+ onClick?: (badge: Badge | null) => void
160
+ /** Extra classes merged onto the outer row. */
161
+ className?: string
162
+ }
163
+ ```
164
+
165
+ ### Types
166
+
167
+ #### `ReputationLevel`
168
+
169
+ Reputation level identifiers — used to pick a tier color/label.
170
+
171
+ Apps that need finer granularity can pass a `level` string of any value;
172
+ unknown values fall back to `'newcomer'` styling.
173
+
174
+ ```typescript
175
+ type ReputationLevel = 'newcomer' | 'contributor' | 'trusted' | 'veteran' | 'legend'
176
+ ```
177
+
178
+ ### Functions
179
+
180
+ #### `BadgeShelf(props)`
181
+
182
+ Horizontal row of small badge icons earned by a user — used alongside
183
+ `<ReputationBadge>` to surface community achievements on profile headers,
184
+ post bylines, and detail pages.
185
+
186
+ Each icon shows its name in a native `title` tooltip for low-friction
187
+ accessibility. Clicking a badge invokes `onClick(badge)`; clicking the
188
+ trailing `+N` chip invokes `onClick(null)` so the host page can expand a
189
+ full list.
190
+
191
+ ```typescript
192
+ function BadgeShelf(props: BadgeShelfProps): JSX.Element
193
+ ```
194
+
195
+ - `props` — Component props (see `BadgeShelfProps`).
196
+
197
+ **Returns:** The rendered shelf, or `null` if no badges are supplied.
198
+
199
+ #### `ReputationBadge(props)`
4
200
 
201
+ User reputation / karma display.
202
+
203
+ Renders a numeric score paired with a tier chip whose color reflects the
204
+ derived (or explicit) `level`. Tier color comes from the active ClassMap
205
+ bond's `cm.badge()` helper, so apps swapping styling libraries restyle these
206
+ chips for free.
207
+
208
+ ```typescript
209
+ function ReputationBadge(props: ReputationBadgeProps): JSX.Element
5
210
  ```
6
- npm install @molecule/app-reputation-badge-solid
211
+
212
+ - `props` — Component props (see `ReputationBadgeProps`).
213
+
214
+ **Returns:** The rendered reputation badge element.
215
+
216
+ #### `levelForScore(score, thresholds)`
217
+
218
+ Derive a {@link ReputationLevel} from a numeric score.
219
+
220
+ Picks the highest level whose threshold is met or exceeded. Any score
221
+ below `thresholds.contributor` returns `'newcomer'`.
222
+
223
+ ```typescript
224
+ function levelForScore(score: number, thresholds?: ReputationThresholds): ReputationLevel
7
225
  ```
8
226
 
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.
227
+ - `score` — Reputation score (any non-negative number).
228
+ - `thresholds` — Optional override thresholds; defaults to {@link DEFAULT_THRESHOLDS}.
229
+
230
+ **Returns:** The derived reputation level.
231
+
232
+ #### `colorForLevel(level)`
233
+
234
+ Return the semantic Badge color for a given level.
235
+
236
+ Unknown levels fall back to `'secondary'`.
237
+
238
+ ```typescript
239
+ function colorForLevel(
240
+ level: ReputationLevel,
241
+ ): 'primary' | 'secondary' | 'success' | 'warning' | 'info'
242
+ ```
243
+
244
+ - `level` — The reputation level.
245
+
246
+ **Returns:** A badge color name from `@molecule/app-ui-vue`.
247
+
248
+ ### Constants
249
+
250
+ #### `DEFAULT_THRESHOLDS`
251
+
252
+ Default thresholds used when no `thresholds` prop is supplied.
253
+
254
+ ```typescript
255
+ const DEFAULT_THRESHOLDS: ReputationThresholds
256
+ ```
257
+
258
+ ## Injection Notes
259
+
260
+ ### Requirements
261
+
262
+ Peer dependencies:
263
+
264
+ - `@molecule/app-solid` ^3.5.0
265
+ - `@molecule/app-ui` ^1.0.1
266
+ - `@molecule/app-ui-solid` ^1.1.0
267
+ - `solid-js` ^1.8.0
268
+
269
+ ### Runtime Dependencies
270
+
271
+ - `@molecule/app-solid`
272
+ - `@molecule/app-ui`
273
+ - `@molecule/app-ui-solid`
274
+ - `solid-js`
275
+
276
+ - Both components throw unless rendered inside `MoleculeProvider` with
277
+ `i18n` (`useTranslation()` needs it) and a ClassMap bonded via
278
+ `setClassMap()`.
279
+ - This package exports a `Badge` TYPE (earned-badge data shape) — distinct
280
+ from the `Badge` COMPONENT in `@molecule/app-ui-solid`; alias one when
281
+ importing both in a file.
282
+ - Server-side score/badge issuance pairs with `@molecule/api-reputation`.
283
+ - Translations live in the companion `@molecule/app-locales-reputation-badge`
284
+ bond (registered).
285
+
286
+ ## Translations
10
287
 
11
- License: Apache-2.0
288
+ 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-solid",
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-solid",
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-solid": "3.7.2",
57
- "@molecule/app-ui": "1.4.0",
58
- "@molecule/app-ui-solid": "1.1.5",
56
+ "@molecule/app-solid": "3.9.0",
57
+ "@molecule/app-ui": "1.5.0",
58
+ "@molecule/app-ui-solid": "1.2.1",
59
59
  "@types/node": "26.6.5",
60
60
  "jsdom": "30.1.3",
61
61
  "solid-js": "1.9.17",