@digilogiclabs/platform-core 1.18.0 → 1.20.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.
@@ -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 };