@digilogiclabs/platform-core 1.19.0 → 1.20.1
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/dist/email-templates.js +2 -1
- package/dist/email-templates.js.map +1 -1
- package/dist/email-templates.mjs +2 -1
- package/dist/email-templates.mjs.map +1 -1
- package/dist/pdf-exports/index.d.mts +366 -0
- package/dist/pdf-exports/index.d.ts +366 -0
- package/dist/pdf-exports/index.js +317 -0
- package/dist/pdf-exports/index.js.map +1 -0
- package/dist/pdf-exports/index.mjs +273 -0
- package/dist/pdf-exports/index.mjs.map +1 -0
- package/package.json +24 -2
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
import { ReactElement, ReactNode } from 'react';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Brand color palette consumed by PDF chrome (header borders, wordmark color, footer text, etc).
|
|
5
|
+
*
|
|
6
|
+
* Apps map their own brand tokens onto these semantic slots — the shared chrome only
|
|
7
|
+
* references `colors.primary`, `colors.secondary`, `colors.ink`, and `colors.muted`.
|
|
8
|
+
* `surface` and `cream` are reserved for future body-content variants.
|
|
9
|
+
*/
|
|
10
|
+
interface BrandColors {
|
|
11
|
+
/** Primary accent — header/footer rule borders, "highlight" color. */
|
|
12
|
+
primary: string;
|
|
13
|
+
/** Secondary accent — wordmark text, secondary headings. */
|
|
14
|
+
secondary: string;
|
|
15
|
+
/** Body text foreground. Also used for default QR module color. */
|
|
16
|
+
ink: string;
|
|
17
|
+
/** Muted text — captions, eyebrow labels, footer date. */
|
|
18
|
+
muted: string;
|
|
19
|
+
/** Page background (reserved for body slots). */
|
|
20
|
+
surface?: string;
|
|
21
|
+
/** Optional warm surface variant (e.g., callout cards). */
|
|
22
|
+
cream?: string;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Logo style variant resolved by the brand's logo render functions.
|
|
26
|
+
*
|
|
27
|
+
* - `original` — full-color brand mark
|
|
28
|
+
* - `mono-light` — single-color white (for dark surfaces)
|
|
29
|
+
* - `mono-dark` — single-color ink (for light surfaces)
|
|
30
|
+
*/
|
|
31
|
+
type LogoVariant = "original" | "mono-light" | "mono-dark";
|
|
32
|
+
/**
|
|
33
|
+
* Props passed by the shared chrome to the brand's logo render functions.
|
|
34
|
+
*/
|
|
35
|
+
interface LogoMarkRenderProps {
|
|
36
|
+
size: number;
|
|
37
|
+
variant: LogoVariant;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Branded export prominence — modulates the SIZE of brand chrome, never removes it.
|
|
41
|
+
*
|
|
42
|
+
* - `maximum` — full-size logo, tagline visible, full QR (free / anonymous tiers)
|
|
43
|
+
* - `refined` — compact logo, tagline hidden, smaller QR (supporter / patron tiers)
|
|
44
|
+
* - `custom` — placement-customizable (reserved; renders identically to `refined` today)
|
|
45
|
+
*/
|
|
46
|
+
type ExportProminence = "maximum" | "refined" | "custom";
|
|
47
|
+
/**
|
|
48
|
+
* App-supplied tier identifier passed into `tierToProminence`.
|
|
49
|
+
*
|
|
50
|
+
* Recognized values map to prominence levels; unrecognized strings or `null` fall back
|
|
51
|
+
* to `maximum`. Apps can use any string token (e.g., `"plus"`, `"pro"`) and supply their
|
|
52
|
+
* own mapping via `BrandConfig.prominenceMap`.
|
|
53
|
+
*/
|
|
54
|
+
type ExportTier = "patron" | "supporter" | "free" | "anonymous" | (string & {}) | null;
|
|
55
|
+
/**
|
|
56
|
+
* Full brand configuration injected into all PDF chrome components.
|
|
57
|
+
*
|
|
58
|
+
* Every consumer app supplies one canonical `BrandConfig` (typically in
|
|
59
|
+
* `src/lib/brand.ts` or `src/lib/exports/brand.ts`) and passes it through to
|
|
60
|
+
* shared components. The shared package itself ships no brand data — apps own
|
|
61
|
+
* their identity entirely.
|
|
62
|
+
*/
|
|
63
|
+
interface BrandConfig {
|
|
64
|
+
/** App display name (e.g., "OpenSourceSports", "DigiLogicLabs"). */
|
|
65
|
+
name: string;
|
|
66
|
+
/** Public domain (e.g., "opensourcesports.io"). Used for footer URL + UTM links. */
|
|
67
|
+
domain: string;
|
|
68
|
+
/** Optional tagline shown in maximum-prominence footer (e.g., "Where Sports Are Defined"). */
|
|
69
|
+
tagline?: string;
|
|
70
|
+
/** CSS font stack for HTML/satori contexts. PDF rendering uses built-in Helvetica. */
|
|
71
|
+
fontStack?: string;
|
|
72
|
+
/** Brand color palette. */
|
|
73
|
+
colors: BrandColors;
|
|
74
|
+
/**
|
|
75
|
+
* Renders the brand mark for HTML / satori / web contexts (e.g., social cards,
|
|
76
|
+
* /print preview pages). Apps must supply their own logo geometry.
|
|
77
|
+
*/
|
|
78
|
+
renderLogoMark: (props: LogoMarkRenderProps) => ReactElement;
|
|
79
|
+
/**
|
|
80
|
+
* Renders the brand mark for react-pdf contexts (uses <Svg>/<Path> from
|
|
81
|
+
* @react-pdf/renderer). Apps must supply their own logo geometry.
|
|
82
|
+
*/
|
|
83
|
+
renderLogoMarkPdf: (props: LogoMarkRenderProps) => ReactElement;
|
|
84
|
+
/**
|
|
85
|
+
* Optional override for `tierToProminence` — apps with custom tier vocabularies
|
|
86
|
+
* (e.g., "plus" / "pro") can supply their own mapping. Falls back to defaults
|
|
87
|
+
* if omitted.
|
|
88
|
+
*/
|
|
89
|
+
prominenceMap?: (tier: ExportTier) => ExportProminence;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* A persistable user-defined export profile, template-agnostic.
|
|
93
|
+
*
|
|
94
|
+
* One profile fills any export type — bracket, scoreboard, round-robin, rules sheet, etc.
|
|
95
|
+
* App-side schemas mirror this shape (typically as `print_profiles` table with
|
|
96
|
+
* `header_data jsonb` + `body_data jsonb`).
|
|
97
|
+
*
|
|
98
|
+
* `headerData` keys are reserved for "who is this document for" details (gym name,
|
|
99
|
+
* address, contact). `bodyData` keys are reserved for content-layer overrides
|
|
100
|
+
* (custom house rules, footer notes).
|
|
101
|
+
*/
|
|
102
|
+
interface PrintProfile {
|
|
103
|
+
/** Stable identifier (UUID or app-defined). */
|
|
104
|
+
id: string;
|
|
105
|
+
/** URL-safe slug, unique per user. */
|
|
106
|
+
slug: string;
|
|
107
|
+
/** Human-readable name (e.g., "Gleason's Gymnastics"). */
|
|
108
|
+
displayName: string;
|
|
109
|
+
/**
|
|
110
|
+
* "Who is this for" header details — gymName, address, contact, customLogoUrl, etc.
|
|
111
|
+
* Schema is intentionally open; apps can add fields without migrations.
|
|
112
|
+
*/
|
|
113
|
+
headerData: Record<string, unknown>;
|
|
114
|
+
/**
|
|
115
|
+
* Content-layer overrides — houseRules, customFooter, etc.
|
|
116
|
+
* Schema is intentionally open; apps can add fields without migrations.
|
|
117
|
+
*/
|
|
118
|
+
bodyData: Record<string, unknown>;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Default tier → prominence mapping.
|
|
123
|
+
*
|
|
124
|
+
* Patron and supporter tiers earn `refined` prominence (smaller branding chrome,
|
|
125
|
+
* tagline hidden). All other tiers — including signed-in free users and anonymous
|
|
126
|
+
* visitors — receive `maximum` prominence so OSS/app branding stays visible.
|
|
127
|
+
*
|
|
128
|
+
* Branding is **never removed**, only modulated in size and detail. Apps that need
|
|
129
|
+
* a different vocabulary (e.g., "plus" / "pro") should supply
|
|
130
|
+
* `BrandConfig.prominenceMap` instead of forking this function.
|
|
131
|
+
*
|
|
132
|
+
* @example
|
|
133
|
+
* ```ts
|
|
134
|
+
* tierToProminence("patron"); // "refined"
|
|
135
|
+
* tierToProminence("supporter"); // "refined"
|
|
136
|
+
* tierToProminence("free"); // "maximum"
|
|
137
|
+
* tierToProminence(null); // "maximum"
|
|
138
|
+
* tierToProminence("plus"); // "maximum" (unknown token falls back)
|
|
139
|
+
* ```
|
|
140
|
+
*/
|
|
141
|
+
declare function tierToProminence(tier: ExportTier): ExportProminence;
|
|
142
|
+
/**
|
|
143
|
+
* Resolve prominence for a brand — uses the brand's `prominenceMap` if supplied,
|
|
144
|
+
* otherwise the default `tierToProminence` mapping.
|
|
145
|
+
*/
|
|
146
|
+
declare function resolveProminence(brand: BrandConfig, tier: ExportTier): ExportProminence;
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* QR code generation for branded export footers.
|
|
150
|
+
*
|
|
151
|
+
* Uses the `qrcode` package (optional peer dependency). Calls return a base64
|
|
152
|
+
* data URL ready to be embedded as an `<Image src={...}>` in react-pdf or as a
|
|
153
|
+
* standard `<img>` in HTML preview routes.
|
|
154
|
+
*
|
|
155
|
+
* Failures (invalid URL, encoder errors) return `null` rather than throwing —
|
|
156
|
+
* exports should degrade gracefully without a QR rather than failing the whole
|
|
157
|
+
* PDF render.
|
|
158
|
+
*/
|
|
159
|
+
interface GenerateQrDataUrlOptions {
|
|
160
|
+
/** Output pixel size (square). Default: 320. */
|
|
161
|
+
size?: number;
|
|
162
|
+
/** Quiet-zone margin in modules. Default: 1. */
|
|
163
|
+
margin?: number;
|
|
164
|
+
/** Module (foreground) color. Default: "#0c1f22" (dark ink). */
|
|
165
|
+
darkColor?: string;
|
|
166
|
+
/** Background color. Default: "#ffffff". */
|
|
167
|
+
lightColor?: string;
|
|
168
|
+
/**
|
|
169
|
+
* Error-correction level. Default: "M" (15% recovery — balances density vs durability
|
|
170
|
+
* on printed sheets that may scuff or fold).
|
|
171
|
+
*/
|
|
172
|
+
errorCorrectionLevel?: "L" | "M" | "Q" | "H";
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Generate a QR code as a base64 PNG data URL.
|
|
176
|
+
*
|
|
177
|
+
* @param url - The URL to encode (typically a UTM-tagged link back to the live page).
|
|
178
|
+
* @param options - Color, size, and error-correction overrides.
|
|
179
|
+
* @returns Data URL string, or `null` on failure.
|
|
180
|
+
*
|
|
181
|
+
* @example
|
|
182
|
+
* ```ts
|
|
183
|
+
* const qrDataUrl = await generateQrDataUrl(
|
|
184
|
+
* "https://opensourcesports.io/rules/basketball?utm_source=export",
|
|
185
|
+
* { darkColor: brand.colors.ink },
|
|
186
|
+
* );
|
|
187
|
+
* if (qrDataUrl) {
|
|
188
|
+
* // <Image src={qrDataUrl} style={...} />
|
|
189
|
+
* }
|
|
190
|
+
* ```
|
|
191
|
+
*/
|
|
192
|
+
declare function generateQrDataUrl(url: string, options?: GenerateQrDataUrlOptions): Promise<string | null>;
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* Export medium — used in UTM tagging and filename suffixes.
|
|
196
|
+
*/
|
|
197
|
+
type ExportMedium = "pdf" | "png" | "ical" | "csv" | "tsv";
|
|
198
|
+
/**
|
|
199
|
+
* File extension — distinct from medium because iCal uses `.ics` not `.ical`.
|
|
200
|
+
*/
|
|
201
|
+
type ExportFileExt = "pdf" | "png" | "ics" | "csv" | "tsv";
|
|
202
|
+
interface BuildExportUrlInput {
|
|
203
|
+
/** Brand config — supplies the domain. */
|
|
204
|
+
brand: BrandConfig;
|
|
205
|
+
/**
|
|
206
|
+
* Tool / template identifier (e.g., "bracket-generator", "rules", "scoreboard").
|
|
207
|
+
* Becomes part of the URL path and `utm_tool`.
|
|
208
|
+
*/
|
|
209
|
+
tool: string;
|
|
210
|
+
/** Export medium for `utm_medium`. */
|
|
211
|
+
medium: ExportMedium;
|
|
212
|
+
/**
|
|
213
|
+
* Optional share-link slug — when present, the URL points at `/s/<slug>` rather than
|
|
214
|
+
* `/tools/<tool>` so QR scanners land on the actual shared artifact.
|
|
215
|
+
*/
|
|
216
|
+
shareSlug?: string;
|
|
217
|
+
/**
|
|
218
|
+
* Optional URL path override. When supplied, replaces both `/s/<slug>` and
|
|
219
|
+
* `/tools/<tool>` defaults. Useful for non-tool exports (e.g., `/rules/basketball`).
|
|
220
|
+
*/
|
|
221
|
+
path?: string;
|
|
222
|
+
/** Optional extra UTM/query params merged into the URL. */
|
|
223
|
+
params?: Record<string, string>;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Build a UTM-tagged URL for QR codes / footer links on branded exports.
|
|
227
|
+
*
|
|
228
|
+
* Every printed sheet that scans back to the live page becomes a measurable acquisition
|
|
229
|
+
* channel — the UTM trio (`utm_source=export`, `utm_medium=<medium>`, `utm_tool=<tool>`)
|
|
230
|
+
* lets analytics attribute traffic to specific export types.
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* ```ts
|
|
234
|
+
* buildExportUrl({
|
|
235
|
+
* brand: ossBrand,
|
|
236
|
+
* tool: "rules",
|
|
237
|
+
* medium: "pdf",
|
|
238
|
+
* path: "/rules/basketball",
|
|
239
|
+
* });
|
|
240
|
+
* // → "https://opensourcesports.io/rules/basketball?utm_source=export&utm_medium=pdf&utm_tool=rules"
|
|
241
|
+
* ```
|
|
242
|
+
*/
|
|
243
|
+
declare function buildExportUrl({ brand, tool, medium, shareSlug, path, params, }: BuildExportUrlInput): string;
|
|
244
|
+
interface BuildExportFilenameInput {
|
|
245
|
+
/** Brand config — supplies the filename prefix. */
|
|
246
|
+
brand: BrandConfig;
|
|
247
|
+
/** Tool / template identifier. */
|
|
248
|
+
tool: string;
|
|
249
|
+
/** Optional title or date suffix (slugified). */
|
|
250
|
+
titleOrDate?: string;
|
|
251
|
+
/** File extension. */
|
|
252
|
+
ext: ExportFileExt;
|
|
253
|
+
}
|
|
254
|
+
/**
|
|
255
|
+
* Build a filename of the form `{brand-slug}-{tool}[-{title-slug}].{ext}`.
|
|
256
|
+
*
|
|
257
|
+
* The brand slug is derived from `brand.name` (lowercased, hyphenated) so the filename
|
|
258
|
+
* carries brand identity even when downloaded outside the app context.
|
|
259
|
+
*
|
|
260
|
+
* @example
|
|
261
|
+
* ```ts
|
|
262
|
+
* buildExportFilename({
|
|
263
|
+
* brand: ossBrand,
|
|
264
|
+
* tool: "rules",
|
|
265
|
+
* titleOrDate: "Basketball NBA",
|
|
266
|
+
* ext: "pdf",
|
|
267
|
+
* });
|
|
268
|
+
* // → "opensourcesports-rules-basketball-nba.pdf"
|
|
269
|
+
* ```
|
|
270
|
+
*/
|
|
271
|
+
declare function buildExportFilename({ brand, tool, titleOrDate, ext, }: BuildExportFilenameInput): string;
|
|
272
|
+
|
|
273
|
+
interface ExportHeaderPdfProps {
|
|
274
|
+
/** Brand configuration. */
|
|
275
|
+
brand: BrandConfig;
|
|
276
|
+
/** Document title (e.g., "Basketball (NBA) — Official Rules"). */
|
|
277
|
+
title: string;
|
|
278
|
+
/** Small uppercase eyebrow above the title (e.g., "Rules Sheet", "Bracket Generator"). */
|
|
279
|
+
toolLabel: string;
|
|
280
|
+
/** Optional supplemental line under the title. */
|
|
281
|
+
subtitle?: string;
|
|
282
|
+
/** Branding prominence. Defaults to `maximum`. */
|
|
283
|
+
prominence?: ExportProminence;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Branded PDF document header — first-page only by default.
|
|
287
|
+
*
|
|
288
|
+
* Renders eyebrow + title + optional subtitle on the left, brand mark + wordmark on
|
|
289
|
+
* the right, with a primary-color rule below.
|
|
290
|
+
*/
|
|
291
|
+
declare function ExportHeaderPdf({ brand, title, toolLabel, subtitle, prominence, }: ExportHeaderPdfProps): ReactElement;
|
|
292
|
+
interface ExportFooterPdfProps {
|
|
293
|
+
/** Brand configuration. */
|
|
294
|
+
brand: BrandConfig;
|
|
295
|
+
/** Public URL displayed in footer (typically UTM-tagged via `buildExportUrl`). */
|
|
296
|
+
url: string;
|
|
297
|
+
/** Generation date label (e.g., "Generated April 26, 2026"). */
|
|
298
|
+
dateLabel?: string;
|
|
299
|
+
/** Pre-rendered QR data URL (from `generateQrDataUrl`). Pass `null` to omit. */
|
|
300
|
+
qrDataUrl?: string | null;
|
|
301
|
+
/** Branding prominence. Defaults to `maximum`. */
|
|
302
|
+
prominence?: ExportProminence;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Branded PDF document footer — `fixed` so it renders on every page.
|
|
306
|
+
*
|
|
307
|
+
* Composition: brand mark + name (left), URL + date (center-right), QR (far right).
|
|
308
|
+
* Tagline shown only at `maximum` prominence; QR shrinks at `refined`.
|
|
309
|
+
*/
|
|
310
|
+
declare function ExportFooterPdf({ brand, url, dateLabel, qrDataUrl, prominence, }: ExportFooterPdfProps): ReactElement;
|
|
311
|
+
interface BrandedPdfPageProps {
|
|
312
|
+
/** Brand configuration. */
|
|
313
|
+
brand: BrandConfig;
|
|
314
|
+
/** Document title shown in the header. */
|
|
315
|
+
title: string;
|
|
316
|
+
/** Eyebrow label above the title. */
|
|
317
|
+
toolLabel: string;
|
|
318
|
+
/** Optional subtitle under the title. */
|
|
319
|
+
subtitle?: string;
|
|
320
|
+
/** Footer URL (typically UTM-tagged). */
|
|
321
|
+
url: string;
|
|
322
|
+
/** Footer date label. */
|
|
323
|
+
dateLabel?: string;
|
|
324
|
+
/** Pre-rendered QR data URL. */
|
|
325
|
+
qrDataUrl?: string | null;
|
|
326
|
+
/** Branding prominence. Defaults to `maximum`. */
|
|
327
|
+
prominence?: ExportProminence;
|
|
328
|
+
/**
|
|
329
|
+
* Optional react-pdf Page-level style overrides (e.g., padding, fontFamily).
|
|
330
|
+
* Merged onto the default page styles.
|
|
331
|
+
*/
|
|
332
|
+
pageStyle?: Record<string, unknown>;
|
|
333
|
+
/** Optional react-pdf page size. Defaults to "LETTER". */
|
|
334
|
+
size?: "LETTER" | "A4" | "LEGAL" | "TABLOID";
|
|
335
|
+
/** Document body — your selected sections, content, etc. */
|
|
336
|
+
children: ReactNode;
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Full branded PDF page wrapper — composes header + body slot + sticky footer.
|
|
340
|
+
*
|
|
341
|
+
* The footer is `fixed` so it renders on every page automatically. The header is
|
|
342
|
+
* first-page only; if you need a per-page compact strip on page 2+, use
|
|
343
|
+
* `ExportHeaderPdf` with your own placement logic.
|
|
344
|
+
*
|
|
345
|
+
* @example
|
|
346
|
+
* ```tsx
|
|
347
|
+
* import { Document } from "@react-pdf/renderer";
|
|
348
|
+
* import { BrandedPdfPage } from "@digilogiclabs/platform-core/pdf-exports";
|
|
349
|
+
*
|
|
350
|
+
* <Document>
|
|
351
|
+
* <BrandedPdfPage
|
|
352
|
+
* brand={ossBrand}
|
|
353
|
+
* title="Basketball — Official Rules"
|
|
354
|
+
* toolLabel="Rules Sheet"
|
|
355
|
+
* url="https://opensourcesports.io/rules/basketball?utm_source=export"
|
|
356
|
+
* qrDataUrl={qrDataUrl}
|
|
357
|
+
* prominence={tierToProminence(userTier)}
|
|
358
|
+
* >
|
|
359
|
+
* <RulesBody sections={selectedSections} />
|
|
360
|
+
* </BrandedPdfPage>
|
|
361
|
+
* </Document>
|
|
362
|
+
* ```
|
|
363
|
+
*/
|
|
364
|
+
declare function BrandedPdfPage({ brand, title, toolLabel, subtitle, url, dateLabel, qrDataUrl, prominence, pageStyle, size, children, }: BrandedPdfPageProps): ReactElement;
|
|
365
|
+
|
|
366
|
+
export { type BrandColors, type BrandConfig, BrandedPdfPage, type BrandedPdfPageProps, type BuildExportFilenameInput, type BuildExportUrlInput, type ExportFileExt, ExportFooterPdf, type ExportFooterPdfProps, ExportHeaderPdf, type ExportHeaderPdfProps, type ExportMedium, type ExportProminence, type ExportTier, type GenerateQrDataUrlOptions, type LogoMarkRenderProps, type LogoVariant, type PrintProfile, buildExportFilename, buildExportUrl, generateQrDataUrl, resolveProminence, tierToProminence };
|