badgesmith 0.0.1 → 1.0.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/LICENSE ADDED
@@ -0,0 +1,48 @@
1
+ ISC License
2
+
3
+ Copyright (c) 2026 Blake Vandercar
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
+
17
+ --------------------------------------------------------------------------------
18
+
19
+ The icon paths bundled in this package come from two sources, under their own
20
+ terms.
21
+
22
+ Octicons (https://github.com/primer/octicons):
23
+
24
+ MIT License
25
+
26
+ Copyright (c) 2026 GitHub Inc.
27
+
28
+ Permission is hereby granted, free of charge, to any person obtaining a copy
29
+ of this software and associated documentation files (the "Software"), to deal
30
+ in the Software without restriction, including without limitation the rights
31
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
32
+ copies of the Software, and to permit persons to whom the Software is
33
+ furnished to do so, subject to the following conditions:
34
+
35
+ The above copyright notice and this permission notice shall be included in all
36
+ copies or substantial portions of the Software.
37
+
38
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
39
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
40
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
41
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
42
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
43
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
44
+ SOFTWARE.
45
+
46
+ Simple Icons (https://github.com/simple-icons/simple-icons) are released under
47
+ CC0 1.0 Universal. The marks they draw remain the trademarks of their owners;
48
+ see https://github.com/simple-icons/simple-icons/blob/develop/DISCLAIMER.md.
package/README.md ADDED
@@ -0,0 +1,269 @@
1
+ <!-- GENERATED FILE — do not edit directly. Edit site/ and run `pnpm gen:pages` -->
2
+
3
+ # badgesmith
4
+
5
+ Renders several icon/value pairs as a **single** SVG badge, on demand.
6
+
7
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=git-commit:370,git-pull-request:264"><img src="https://badgesmith.bvandrc.workers.dev/?items=git-commit:370,git-pull-request:264" alt="370 commits, 264 pull requests"/></a>
8
+
9
+ ```
10
+ https://badgesmith.bvandrc.workers.dev/?items=git-commit:370,git-pull-request:264
11
+ ```
12
+
13
+ Open [the worker](https://badgesmith.bvandrc.workers.dev) in a browser for a page of live examples.
14
+
15
+ ## Examples
16
+
17
+ Every badge below is fetched live from the deployed worker — copy a URL, change the values, and use it as an image anywhere.
18
+
19
+ **Live numbers for any public repo, looked up by the worker**
20
+
21
+ <a href="https://badgesmith.bvandrc.workers.dev/github?repo=bvandrc/badgesmith"><img src="https://badgesmith.bvandrc.workers.dev/github?repo=bvandrc/badgesmith" alt="Live numbers for any public repo, looked up by the worker"/></a>
22
+
23
+ ```
24
+ https://badgesmith.bvandrc.workers.dev/github?repo=bvandrc/badgesmith
25
+ ```
26
+
27
+ **Your own colors, rounded corners**
28
+
29
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=star:1.2k,repo-forked:89,eye:42&amp;color=1f6feb&amp;iconColor=fff&amp;radius=6"><img src="https://badgesmith.bvandrc.workers.dev/?items=star:1.2k,repo-forked:89,eye:42&amp;color=1f6feb&amp;iconColor=fff&amp;radius=6" alt="Your own colors, rounded corners"/></a>
30
+
31
+ ```
32
+ https://badgesmith.bvandrc.workers.dev/?items=star:1.2k,repo-forked:89,eye:42&color=1f6feb&iconColor=fff&radius=6
33
+ ```
34
+
35
+ **Status and version, not just counts**
36
+
37
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=check-circle:passing,shield-check:A%2B,versions:v2.1.0&amp;color=1a7f37&amp;iconColor=fff"><img src="https://badgesmith.bvandrc.workers.dev/?items=check-circle:passing,shield-check:A%2B,versions:v2.1.0&amp;color=1a7f37&amp;iconColor=fff" alt="Status and version, not just counts"/></a>
38
+
39
+ ```
40
+ https://badgesmith.bvandrc.workers.dev/?items=check-circle:passing,shield-check:A%2B,versions:v2.1.0&color=1a7f37&iconColor=fff
41
+ ```
42
+
43
+ **A value with no icon reads as a label**
44
+
45
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=stable,tag:v2.1.0,law:MIT&amp;color=8250df&amp;iconColor=fff"><img src="https://badgesmith.bvandrc.workers.dev/?items=stable,tag:v2.1.0,law:MIT&amp;color=8250df&amp;iconColor=fff" alt="A value with no icon reads as a label"/></a>
46
+
47
+ ```
48
+ https://badgesmith.bvandrc.workers.dev/?items=stable,tag:v2.1.0,law:MIT&color=8250df&iconColor=fff
49
+ ```
50
+
51
+ **The same mark as an icon and as an emoji — an emoji is text, so it keeps its own colours**
52
+
53
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=rocket:shipped,%F0%9F%9A%80%20shipped&amp;color=1f6feb&amp;iconColor=fff"><img src="https://badgesmith.bvandrc.workers.dev/?items=rocket:shipped,%F0%9F%9A%80%20shipped&amp;color=1f6feb&amp;iconColor=fff" alt="The same mark as an icon and as an emoji — an emoji is text, so it keeps its own colours"/></a>
54
+
55
+ ```
56
+ https://badgesmith.bvandrc.workers.dev/?items=rocket:shipped,%F0%9F%9A%80%20shipped&color=1f6feb&iconColor=fff
57
+ ```
58
+
59
+ **An icon on its own, written with a trailing colon**
60
+
61
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=shield-check:,law:MIT,tag:v2.1.0&amp;color=1a7f37&amp;iconColor=fff"><img src="https://badgesmith.bvandrc.workers.dev/?items=shield-check:,law:MIT,tag:v2.1.0&amp;color=1a7f37&amp;iconColor=fff" alt="An icon on its own, written with a trailing colon"/></a>
62
+
63
+ ```
64
+ https://badgesmith.bvandrc.workers.dev/?items=shield-check:,law:MIT,tag:v2.1.0&color=1a7f37&iconColor=fff
65
+ ```
66
+
67
+ **Brand marks for what a project is built with**
68
+
69
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=typescript:5.9,react:19,vite:7&amp;color=1f2328&amp;iconColor=fff"><img src="https://badgesmith.bvandrc.workers.dev/?items=typescript:5.9,react:19,vite:7&amp;color=1f2328&amp;iconColor=fff" alt="Brand marks for what a project is built with"/></a>
70
+
71
+ ```
72
+ https://badgesmith.bvandrc.workers.dev/?items=typescript:5.9,react:19,vite:7&color=1f2328&iconColor=fff
73
+ ```
74
+
75
+ **Brand marks with no values at all**
76
+
77
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=python:,postgresql:,docker:&amp;color=none&amp;iconColor=8B949E&amp;height=20&amp;padY=0"><img src="https://badgesmith.bvandrc.workers.dev/?items=python:,postgresql:,docker:&amp;color=none&amp;iconColor=8B949E&amp;height=20&amp;padY=0" alt="Brand marks with no values at all"/></a>
78
+
79
+ ```
80
+ https://badgesmith.bvandrc.workers.dev/?items=python:,postgresql:,docker:&color=none&iconColor=8B949E&height=20&padY=0
81
+ ```
82
+
83
+ **Up to six items**
84
+
85
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=issue-opened:12,issue-closed:340,git-merge:211,comment-discussion:58,people:23,heart:1k&amp;radius=4"><img src="https://badgesmith.bvandrc.workers.dev/?items=issue-opened:12,issue-closed:340,git-merge:211,comment-discussion:58,people:23,heart:1k&amp;radius=4" alt="Up to six items"/></a>
86
+
87
+ ```
88
+ https://badgesmith.bvandrc.workers.dev/?items=issue-opened:12,issue-closed:340,git-merge:211,comment-discussion:58,people:23,heart:1k&radius=4
89
+ ```
90
+
91
+ **Bold values, fully rounded**
92
+
93
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=flame:hot,zap:fast,rocket:shipped&amp;color=bf3989&amp;iconColor=fff&amp;bold=true&amp;radius=10"><img src="https://badgesmith.bvandrc.workers.dev/?items=flame:hot,zap:fast,rocket:shipped&amp;color=bf3989&amp;iconColor=fff&amp;bold=true&amp;radius=10" alt="Bold values, fully rounded"/></a>
94
+
95
+ ```
96
+ https://badgesmith.bvandrc.workers.dev/?items=flame:hot,zap:fast,rocket:shipped&color=bf3989&iconColor=fff&bold=true&radius=10
97
+ ```
98
+
99
+ **Taller, as a pill**
100
+
101
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=logo-github:49,tag:v2.1.0&amp;height=28&amp;radius=14"><img src="https://badgesmith.bvandrc.workers.dev/?items=logo-github:49,tag:v2.1.0&amp;height=28&amp;radius=14" alt="Taller, as a pill"/></a>
102
+
103
+ ```
104
+ https://badgesmith.bvandrc.workers.dev/?items=logo-github:49,tag:v2.1.0&height=28&radius=14
105
+ ```
106
+
107
+ **Icons after their values**
108
+
109
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=git-commit:370,git-pull-request:264&amp;iconSide=right"><img src="https://badgesmith.bvandrc.workers.dev/?items=git-commit:370,git-pull-request:264&amp;iconSide=right" alt="Icons after their values"/></a>
110
+
111
+ ```
112
+ https://badgesmith.bvandrc.workers.dev/?items=git-commit:370,git-pull-request:264&iconSide=right
113
+ ```
114
+
115
+ **Light pill, dark text**
116
+
117
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=clock:2h,calendar:Nov%202026&amp;color=f6f8fa&amp;textColor=1f2328&amp;iconColor=59636e&amp;radius=6"><img src="https://badgesmith.bvandrc.workers.dev/?items=clock:2h,calendar:Nov%202026&amp;color=f6f8fa&amp;textColor=1f2328&amp;iconColor=59636e&amp;radius=6" alt="Light pill, dark text"/></a>
118
+
119
+ ```
120
+ https://badgesmith.bvandrc.workers.dev/?items=clock:2h,calendar:Nov%202026&color=f6f8fa&textColor=1f2328&iconColor=59636e&radius=6
121
+ ```
122
+
123
+ **No background — reads as a link**
124
+
125
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=book:docs&amp;bold=true&amp;underline=true&amp;color=none&amp;textColor=0969da&amp;iconColor=0969da&amp;iconScale=0.7"><img src="https://badgesmith.bvandrc.workers.dev/?items=book:docs&amp;bold=true&amp;underline=true&amp;color=none&amp;textColor=0969da&amp;iconColor=0969da&amp;iconScale=0.7" alt="No background — reads as a link"/></a>
126
+
127
+ ```
128
+ https://badgesmith.bvandrc.workers.dev/?items=book:docs&bold=true&underline=true&color=none&textColor=0969da&iconColor=0969da&iconScale=0.7
129
+ ```
130
+
131
+ **A label alone, underlined**
132
+
133
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=react-toolkit&amp;bold=true&amp;underline=true&amp;color=none&amp;textColor=0969da"><img src="https://badgesmith.bvandrc.workers.dev/?items=react-toolkit&amp;bold=true&amp;underline=true&amp;color=none&amp;textColor=0969da" alt="A label alone, underlined"/></a>
134
+
135
+ ```
136
+ https://badgesmith.bvandrc.workers.dev/?items=react-toolkit&bold=true&underline=true&color=none&textColor=0969da
137
+ ```
138
+
139
+ **No background, compact, legible on light and dark themes**
140
+
141
+ <a href="https://badgesmith.bvandrc.workers.dev/?items=git-commit:547,git-pull-request:0&amp;color=none&amp;iconColor=6E7681&amp;textColor=6E7681&amp;height=14&amp;padY=0"><img src="https://badgesmith.bvandrc.workers.dev/?items=git-commit:547,git-pull-request:0&amp;color=none&amp;iconColor=6E7681&amp;textColor=6E7681&amp;height=14&amp;padY=0" alt="No background, compact, legible on light and dark themes"/></a>
142
+
143
+ ```
144
+ https://badgesmith.bvandrc.workers.dev/?items=git-commit:547,git-pull-request:0&color=none&iconColor=6E7681&textColor=6E7681&height=14&padY=0
145
+ ```
146
+
147
+ In a README, use markdown or an `<img>` tag — the latter lets you align it:
148
+
149
+ ```md
150
+ ![commits and pull requests](https://badgesmith.bvandrc.workers.dev/github?repo=owner/name)
151
+ ```
152
+
153
+ ```html
154
+ <img src="https://badgesmith.bvandrc.workers.dev/github?repo=owner/name" align="right" alt="commits and pull requests">
155
+ ```
156
+
157
+ ## Why this exists
158
+
159
+ shields.io supports exactly **one** logo per badge, and hard-codes custom SVG logos to a 14×14 box (`DEFAULT_LOGO_HEIGHT`; the aspect-preserving `logoSize=auto` path only runs for named simple-icons). The PR that would have lifted that, [badges/shields#11093](https://github.com/badges/shields/pull/11093), was closed unmerged.
160
+
161
+ So several icons mean several images, and a row of images is not one badge. They size independently, wrap independently, load and fail independently, and the gap between them belongs to whatever is rendering them rather than to you. One request returning one SVG gives you a single element to place, with the spacing settled where the badge is drawn.
162
+
163
+ That last point bites hardest wherever the host adds spacing you can't override. A GitHub README is one such place: its markdown CSS applies `padding-left: 20px` to every `img[align=right]`, and since only `<img>` and `<table>` float via the `align` attribute, two right-aligned badges can never sit flush there.
164
+
165
+ ## Routes
166
+
167
+ ### `GET /` — the usage page
168
+
169
+ Opening the root with no query returns an HTML page of the same examples as above, each rendered by the worker serving it. Any query at all means a badge was intended, so a malformed one still gets a 400 rather than the page.
170
+
171
+ ### `GET /?items=…` — explicit values
172
+
173
+ | param | default | notes |
174
+ | --- | --- | --- |
175
+ | `items` | _required_ | comma-separated `icon:value` pairs, up to 6; a value alone draws without an icon; value 1–64 chars |
176
+ | `color` | `2f363d` | pill background, 3- or 6-digit hex, no `#`, or `none` for no background |
177
+ | `iconColor` | `8B949E` | |
178
+ | `textColor` | `fff` | |
179
+ | `height` | `20` | 12–64; the box the contents are centred in |
180
+ | `padY` | 15% of `height` | 0–32; space above and below the contents, under half of `height` |
181
+ | `iconSide` | `left` | `left` or `right`; which side of its value each icon sits on |
182
+ | `iconScale` | `1` | 0.25–1; how large each icon is against its value |
183
+ | `bold` | `false` | `true` or `false`; draws every value in the bold face |
184
+ | `underline` | `false` | `true` or `false`; draws a line under every value |
185
+ | `radius` | `0` | corner radius; `0` matches shields' flat-square |
186
+ | `font` | `verdana` | `verdana`, `arial`, `times` or `courier` |
187
+ | `fontSize` | from the box | text size in px, independent of `height` |
188
+
189
+ `bold=true` draws the values in Verdana's bold face, measured against that face's own metrics — its glyphs advance further than the regular one's, so measuring bold text against regular widths would leave it wider than the pill drawn for it.
190
+
191
+ `underline=true` draws a line under every value, which costs no width: an underline does not change what a glyph advances by, so the measured text stays the right size. It is a presentation attribute rather than CSS, so GitHub's image proxy serves it intact.
192
+
193
+ `font` picks the face every value is drawn in. Only families a reader already has, since the proxy serving these SVGs forbids fetching a font — and only ones whose advance widths are known, because the pill has to be sized before it is drawn. Each face is measured against its own metrics and centred on its own cap height, so the text fits and sits level whichever is chosen. The stacks name a metric-compatible clone after the family itself (`Arial,Liberation Sans,Helvetica,sans-serif`), so a reader without the family still gets the widths the table holds.
194
+
195
+ A run of ordinary spaces in a value collapses to one when the SVG is drawn, and the CSS that would stop that is blocked by the proxy these are served through — so use non-breaking spaces (`%C2%A0`) for a wider gap. They are measured as spaces, which is exactly what they advance as.
196
+
197
+ Values may carry emoji. They are drawn from the reader's own emoji font, which keeps their colour — a `textColor` does not flatten them — and they are measured by grapheme, so one carrying a variation selector, a flag, or a joined sequence takes a single advance rather than one per code point.
198
+
199
+ `fontSize` sets the text size directly, instead of letting the box set it. By default the text scales with the room `padY` leaves, which ties how large it reads to how tall the badge is — and the height is what badges align by, since an image sits on the line's baseline and a badge centres its contents, so equal heights put equal centres. Setting `fontSize` decouples the two: a badge can hold larger text and still line up with the ones beside it. Only the text moves; the icons, the end padding and the gaps still follow the box.
200
+
201
+ Text too large for its box is refused rather than drawn clipped. The limit depends on the face as well as the room the padding leaves, and the error names it.
202
+
203
+ `iconScale` draws the icons smaller against their values. At 1 an icon fills the height the contents are given, which is taller than the text beside it; lower brings it nearer the text's own size, and the badge narrows by what the icon gives up. It stops at 1 because the icon already fills that height — a larger one would run past the badge and be cut off by its edges.
204
+
205
+ `iconSide=right` draws each icon after its own value instead of before it. The badge is the same width either way — only the order within a pair changes — and the `aria-label` still reads `370 git-commit`, since it says what the badge holds rather than how it is arranged.
206
+
207
+ Contents scale to the room `padY` leaves them, not to `height`, so trimming the padding grows the icons and text rather than cropping the pill. `height=14&padY=0` renders the default 11px text in a 14px box — 14px being as short as it goes at that text size, since the icon is the taller of the two. Going shorter still is allowed and shrinks the text with it.
208
+
209
+ `color=none` draws no background, so the badge sits on whatever is behind it. Nothing then separates the badge from the page, so `iconColor` and `textColor` have to carry their own contrast — a README shown on both GitHub themes wants a mid grey such as `6E7681` rather than the default white text, which disappears on a light background.
210
+
211
+ Values live in the URL, so a changed value is a different URL — the response is cached for a week and can never go stale.
212
+
213
+ ### `GET /<provider>` — live values
214
+
215
+ A **provider** looks values up itself, for a fixed set of icons, so the URL holds no numbers — which is what keeps a generated README reproducible while the numbers stay current. Cached an hour; a lookup that fails renders `?` with a 5-minute cache rather than breaking the image. The style params above apply here too.
216
+
217
+ #### `github`
218
+
219
+ `GET /github?repo=owner/name` renders `git-commit` and `git-pull-request` with the repo's total commits and pull requests. Set a token to raise the rate limit (Cloudflare egress IPs are shared, so the unauthenticated 60/hour is easy to exhaust):
220
+
221
+ ```sh
222
+ wrangler secret put GITHUB_TOKEN
223
+ ```
224
+
225
+ Private repos aren't readable this way — pass their numbers to `/` instead.
226
+
227
+ ### Icons
228
+
229
+ Any [octicon](https://primer.style/foundations/icons) slug works — all 408 of them, square or not — plus 183 brand marks from [simple-icons](https://simpleicons.org) for languages and the tools built around them. Those are a curated set rather than the whole 3,467-icon catalogue, which would be 4.4MB of path data: the list is [scripts/simple-icon-slugs.ts](https://github.com/bvandrc/badgesmith/blob/main/scripts/simple-icon-slugs.ts). Where a slug belongs to both, the octicon keeps it. Something missing? [Open an issue](https://github.com/bvandrc/badgesmith/issues/new) asking for it, or a pull request adding its slug to [that file](https://github.com/bvandrc/badgesmith/blob/main/scripts/simple-icon-slugs.ts) — anything [simple-icons](https://simpleicons.org) has can go in.
230
+
231
+ An item may be an icon on its own, written with a trailing colon — `items=react:`. It draws to the same box as the badges beside it, so it centres with them, which a bare `<img>` of the same mark cannot: an image sits on the line's baseline instead.
232
+
233
+ An item may be an icon on its own, written with a trailing colon — `items=shield-check:`. It draws to the same box as the badges beside it, so it centres with them, which a bare `<img>` of the same mark cannot: an image sits on the line's baseline instead.
234
+
235
+ ## As a package
236
+
237
+ The renderer is also published to npm, for drawing a badge without the worker: at build time, or behind a server of your own.
238
+
239
+ ```sh
240
+ pnpm add badgesmith
241
+ ```
242
+
243
+ ```ts
244
+ import { renderBadge } from 'badgesmith'
245
+
246
+ const svg = renderBadge({
247
+ items: [
248
+ { icon: 'git-commit', value: '370' },
249
+ { icon: 'git-pull-request', value: '264' },
250
+ ],
251
+ height: 18,
252
+ })
253
+ ```
254
+
255
+ `renderBadge` takes `items` plus the same style options as the query params above, typed rather than as strings, and returns the SVG as a string. It holds them to the same limits the worker does, and throws an `InvalidBadgeError` naming the option and the reason for any it cannot draw. `hasIcon` checks a slug before you pass it.
256
+
257
+ ## Development
258
+
259
+ Issues and pull requests are both welcome. [Open an issue](https://github.com/bvandrc/badgesmith/issues/new) for a bug, a missing icon, or an idea, or send a pull request with the change itself.
260
+
261
+ ```sh
262
+ pnpm install
263
+ pnpm dev # the worker, locally
264
+ pnpm check # lint and types
265
+ pnpm test
266
+ pnpm gen:all # regenerate the README, fixtures, and tables; CI fails if they drift
267
+ ```
268
+
269
+ Why the icon registry and the width table are generated, the constraints the renderer works under, and the rest of the commands are in [docs/internals.md](./docs/internals.md).
@@ -0,0 +1,151 @@
1
+ /** The fonts a badge may be drawn in. */
2
+ export declare const BADGE_FONTS: readonly ['verdana', 'arial', 'times', 'courier'];
3
+ type BadgeFont = (typeof BADGE_FONTS)[number];
4
+ /**
5
+ * One thing the badge holds: an icon and its value, or either on its own.
6
+ *
7
+ * An icon alone is how a badge stands in for a bare image — drawn to the same
8
+ * box as the badges beside it, so it centres with them rather than sitting on
9
+ * the line's baseline as an `<img>` would.
10
+ */
11
+ type BadgeItem = {
12
+ icon: string;
13
+ value?: string;
14
+ } | {
15
+ icon?: string;
16
+ value: string;
17
+ };
18
+ /** The sides an icon may sit on, relative to its own value. */
19
+ export declare const ICON_SIDES: readonly ['left', 'right'];
20
+ type IconSide = (typeof ICON_SIDES)[number];
21
+ /** The `color` that draws no background at all, letting the page show through. */
22
+ export declare const TRANSPARENT = "none";
23
+ /** How the pill looks, independent of what it holds. */
24
+ type BadgeStyle = {
25
+ /**
26
+ * Pill background, hex without the leading '#', or `TRANSPARENT` for none.
27
+ *
28
+ * With no background the icons and text carry their own contrast, so a
29
+ * badge meant for both GitHub themes needs a mid grey rather than the
30
+ * default white text.
31
+ *
32
+ * @default '2f363d' — near-black slate grey, GitHub's dark surface
33
+ */
34
+ color?: string;
35
+ /**
36
+ * Icon fill.
37
+ *
38
+ * @default '8B949E' — mid grey, legible on the default background without
39
+ * competing with the value text
40
+ */
41
+ iconColor?: string;
42
+ /**
43
+ * Value fill.
44
+ *
45
+ * @default 'fff' — white
46
+ */
47
+ textColor?: string;
48
+ /**
49
+ * Pill height in px — the box, which the contents are centred in.
50
+ *
51
+ * @default 20 — shields' own flat-square height
52
+ */
53
+ height?: number;
54
+ /**
55
+ * Space above and below the contents in px.
56
+ *
57
+ * The contents scale to the room this leaves rather than to `height`, so
58
+ * trimming it grows the icons and text instead of just cropping the pill.
59
+ * Must leave some room: `padY * 2` below `height`.
60
+ *
61
+ * @default 15% of `height` — the shields proportion, 3px at the default
62
+ */
63
+ padY?: number;
64
+ /**
65
+ * Draws every value in the bold face.
66
+ *
67
+ * Measured against its own metrics, so the pill is the width the heavier
68
+ * glyphs actually need.
69
+ *
70
+ * @default false
71
+ */
72
+ bold?: boolean;
73
+ /**
74
+ * Draws a line under every value.
75
+ *
76
+ * Costs nothing in width: an underline does not change what a glyph
77
+ * advances by, so the measured text is still the right size.
78
+ *
79
+ * @default false
80
+ */
81
+ underline?: boolean;
82
+ /**
83
+ * How large each icon is against its own value, as a fraction of normal.
84
+ *
85
+ * 1 leaves an icon filling the height the contents are given, which is
86
+ * taller than the text beside it; smaller draws it nearer the text's own
87
+ * size. It cannot go above 1: the icon already fills that height, so a
88
+ * larger one would run past the badge and be cut off by its edges.
89
+ *
90
+ * @default 1
91
+ */
92
+ iconScale?: number;
93
+ /**
94
+ * Which side of its value each icon sits on.
95
+ *
96
+ * The badge is the same width either way: only the order within a pair
97
+ * changes, not the room it takes.
98
+ *
99
+ * @default 'left' — the icon leads, as shields' logo does
100
+ */
101
+ iconSide?: IconSide;
102
+ /**
103
+ * Corner radius in px, at the pill's natural height.
104
+ *
105
+ * @default 0 — square corners, matching shields' flat-square
106
+ */
107
+ radius?: number;
108
+ /**
109
+ * Text size in px, overriding the size the box would otherwise set.
110
+ *
111
+ * By default the text scales with the room `padY` leaves, at the renderer's
112
+ * own ratio of font to icon box. Setting it decouples the two, so a badge
113
+ * can hold larger text without growing the box its neighbours align to.
114
+ * Too large for that box is an error rather than a crop.
115
+ *
116
+ * @default 11/14 of the room the contents are given
117
+ */
118
+ fontSize?: number;
119
+ /**
120
+ * Which face every value is drawn in.
121
+ *
122
+ * Only families a reader already has, since the proxy serving this SVG
123
+ * forbids fetching a font. Each is measured against its own metrics, so the
124
+ * pill is the width that face actually needs.
125
+ *
126
+ * @default 'verdana' — shields' own font
127
+ */
128
+ font?: BadgeFont;
129
+ };
130
+ type BadgeOptions = BadgeStyle & {
131
+ items: BadgeItem[];
132
+ };
133
+ /**
134
+ * Badge options that would draw something broken, clipped, or unbounded.
135
+ *
136
+ * Its message names the option and the reason, written for whoever supplied
137
+ * the value, since the Worker sends it back as the body of a 400.
138
+ */
139
+ export declare class InvalidBadgeError extends Error {}
140
+ /** Whether any octicon goes by this slug. */
141
+ export declare const hasIcon: (slug: string) => boolean;
142
+ /**
143
+ * One SVG pill holding every icon/value pair, sized to its contents.
144
+ *
145
+ * Holds the options to the same limits the hosted worker does: up to six
146
+ * items, values of 1–64 characters, hex colors, and each size in its range.
147
+ * Throws `InvalidBadgeError`, naming the option and the reason, for any it
148
+ * cannot draw.
149
+ */
150
+ export declare const renderBadge: (options: BadgeOptions) => string;
151
+ export type { BadgeFont, BadgeItem, BadgeOptions, BadgeStyle, IconSide };