czapp-shared 1.0.38 → 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.
package/dist/index.mjs CHANGED
@@ -1,3 +1,55 @@
1
+ var __defProp = Object.defineProperty;
2
+ var __defProps = Object.defineProperties;
3
+ var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
4
+ var __getOwnPropSymbols = Object.getOwnPropertySymbols;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __propIsEnum = Object.prototype.propertyIsEnumerable;
7
+ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
8
+ var __spreadValues = (a, b) => {
9
+ for (var prop in b || (b = {}))
10
+ if (__hasOwnProp.call(b, prop))
11
+ __defNormalProp(a, prop, b[prop]);
12
+ if (__getOwnPropSymbols)
13
+ for (var prop of __getOwnPropSymbols(b)) {
14
+ if (__propIsEnum.call(b, prop))
15
+ __defNormalProp(a, prop, b[prop]);
16
+ }
17
+ return a;
18
+ };
19
+ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
20
+
21
+ // src/concrete/color.ts
22
+ var hexToHsl = (hex) => {
23
+ let value = hex.replace("#", "");
24
+ if (value.length === 3) value = value.split("").map((c) => c + c).join("");
25
+ const r = parseInt(value.slice(0, 2), 16) / 255;
26
+ const g = parseInt(value.slice(2, 4), 16) / 255;
27
+ const b = parseInt(value.slice(4, 6), 16) / 255;
28
+ const max = Math.max(r, g, b);
29
+ const min = Math.min(r, g, b);
30
+ const l = (max + min) / 2;
31
+ if (max === min) return { h: 0, s: 0, l };
32
+ const d = max - min;
33
+ const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
34
+ const h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
35
+ return { h: h * 60, s, l };
36
+ };
37
+ var hslToHex = ({ h, s, l }) => {
38
+ const hue = (h % 360 + 360) % 360;
39
+ const c = (1 - Math.abs(2 * l - 1)) * s;
40
+ const x = c * (1 - Math.abs(hue / 60 % 2 - 1));
41
+ const m = l - c / 2;
42
+ const [r, g, b] = hue < 60 ? [c, x, 0] : hue < 120 ? [x, c, 0] : hue < 180 ? [0, c, x] : hue < 240 ? [0, x, c] : hue < 300 ? [x, 0, c] : [c, 0, x];
43
+ const toHex = (v) => Math.round((v + m) * 255).toString(16).padStart(2, "0");
44
+ return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
45
+ };
46
+ var shiftHue = (hex, degrees) => {
47
+ if (!degrees) return hex;
48
+ const hsl = hexToHsl(hex);
49
+ return hslToHex(__spreadProps(__spreadValues({}, hsl), { h: hsl.h + degrees }));
50
+ };
51
+ var isHexColor = (value) => typeof value === "string" && /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value);
52
+
1
53
  // src/concrete/date.ts
2
54
  var getMysqlDateIgnoreTZ = (date) => {
3
55
  let dateStr;
@@ -61,6 +113,286 @@ var isExpired = (date) => {
61
113
  return dateObj.getTime() < now.getTime();
62
114
  };
63
115
 
116
+ // src/concrete/level.ts
117
+ var XP_FLASHCARD_REVIEW = 10;
118
+ var XP_TEST = 15;
119
+ var XP_PER_TEST_KNOWN_ANSWER = 1;
120
+ var XP_PER_WORD_RETIRED = 5;
121
+ var XP_DAILY_STREAK_BONUS_CAP = 30;
122
+ var LEVELS = [
123
+ { level: 1, xpThreshold: 0, minBestStreak: 0 },
124
+ { level: 2, xpThreshold: 60, minBestStreak: 0 },
125
+ { level: 3, xpThreshold: 200, minBestStreak: 0 },
126
+ { level: 4, xpThreshold: 450, minBestStreak: 0 },
127
+ { level: 5, xpThreshold: 900, minBestStreak: 7 },
128
+ { level: 6, xpThreshold: 1600, minBestStreak: 14 },
129
+ { level: 7, xpThreshold: 2700, minBestStreak: 21 },
130
+ { level: 8, xpThreshold: 4300, minBestStreak: 30 },
131
+ { level: 9, xpThreshold: 6500, minBestStreak: 45 },
132
+ { level: 10, xpThreshold: 1e4, minBestStreak: 60 }
133
+ ];
134
+ var maxLevel = LEVELS[LEVELS.length - 1].level;
135
+ var meetsRequirements = (level, xp, bestStreak) => xp >= level.xpThreshold && bestStreak >= level.minBestStreak;
136
+ var sorted = (levels) => levels.length < 2 || levels.every((l, i) => i === 0 || levels[i - 1].level < l.level) ? levels : [...levels].sort((a, b) => a.level - b.level);
137
+ var getLevel = (xp, bestStreak, levels = LEVELS) => {
138
+ var _a, _b;
139
+ const ordered = sorted(levels);
140
+ let reached = (_b = (_a = ordered[0]) == null ? void 0 : _a.level) != null ? _b : 1;
141
+ for (const level of ordered) {
142
+ if (!meetsRequirements(level, xp, bestStreak)) {
143
+ break;
144
+ }
145
+ reached = level.level;
146
+ }
147
+ return reached;
148
+ };
149
+ var getLevelProgress = (xp, bestStreak, levels = LEVELS) => {
150
+ const ordered = sorted(levels);
151
+ const level = getLevel(xp, bestStreak, ordered);
152
+ const index = ordered.findIndex((l) => l.level === level);
153
+ const current = ordered[index];
154
+ const next = ordered[index + 1];
155
+ if (!current || !next) {
156
+ return { level, xpToNextLevel: 0, xpProgress: 1, streakDaysToNextLevel: 0 };
157
+ }
158
+ const span = Math.max(1, next.xpThreshold - current.xpThreshold);
159
+ return {
160
+ level,
161
+ nextLevel: next.level,
162
+ xpToNextLevel: Math.max(0, next.xpThreshold - xp),
163
+ xpProgress: Math.min(1, Math.max(0, (xp - current.xpThreshold) / span)),
164
+ streakDaysToNextLevel: Math.max(0, next.minBestStreak - bestStreak)
165
+ };
166
+ };
167
+ var DEFAULT_XP_AWARDS = {
168
+ flashcardReview: XP_FLASHCARD_REVIEW,
169
+ test: XP_TEST,
170
+ perTestKnownAnswer: XP_PER_TEST_KNOWN_ANSWER,
171
+ perWordRetired: XP_PER_WORD_RETIRED,
172
+ dailyStreakBonusCap: XP_DAILY_STREAK_BONUS_CAP
173
+ };
174
+ var getFlashcardReviewXp = (retiredCount, newStreakDayLength, awards = DEFAULT_XP_AWARDS) => awards.flashcardReview + retiredCount * awards.perWordRetired + Math.min(Math.max(0, newStreakDayLength), awards.dailyStreakBonusCap);
175
+ var getTestXp = (knownCount, awards = DEFAULT_XP_AWARDS) => awards.test + knownCount * awards.perTestKnownAnswer;
176
+ var getBestStreak = (user) => {
177
+ var _a, _b;
178
+ return Math.max((_a = user.highStreakLength) != null ? _a : 0, (_b = user.currentStreakLength) != null ? _b : 0);
179
+ };
180
+ var getUserLevelProgress = (user, levels = LEVELS) => {
181
+ var _a;
182
+ return getLevelProgress((_a = user.xp) != null ? _a : 0, getBestStreak(user), levels);
183
+ };
184
+
185
+ // src/design/levels.ts
186
+ var AvatarPresetId = /* @__PURE__ */ ((AvatarPresetId2) => {
187
+ AvatarPresetId2["COOL_CATALYST"] = "coolCatalyst";
188
+ AvatarPresetId2["SWIFT_STARTER"] = "swiftStarter";
189
+ AvatarPresetId2["BOLD_BUILDER"] = "boldBuilder";
190
+ AvatarPresetId2["WORD_WRANGLER"] = "wordWrangler";
191
+ AvatarPresetId2["FLUENT_FLAME"] = "fluentFlame";
192
+ AvatarPresetId2["MIGHTY_MASTER"] = "mightyMaster";
193
+ AvatarPresetId2["RADIANT_ROCKSTAR"] = "radiantRockstar";
194
+ AvatarPresetId2["WISE_WIZARD"] = "wiseWizard";
195
+ AvatarPresetId2["LEGENDARY_LINGUIST"] = "legendaryLinguist";
196
+ AvatarPresetId2["ABSOLUTE_ALPHA"] = "absoluteAlpha";
197
+ return AvatarPresetId2;
198
+ })(AvatarPresetId || {});
199
+
200
+ // src/concrete/levelDefaults.ts
201
+ var DESIGN = {
202
+ background: "#ece7e1",
203
+ card: "#f9f8f6",
204
+ brand: "#317a97",
205
+ brandMid: "#76b2cb",
206
+ brandLight: "#a7d2e4",
207
+ brandPale: "#cedfe8",
208
+ points: "#fcb64a",
209
+ streak: "#f0643f",
210
+ test: "#80bda6",
211
+ testDark: "#326451",
212
+ testText: "#4c836e",
213
+ leaderboardHighlight: "#fbe6c4",
214
+ divider: "#d9d3c9",
215
+ heatScale: ["#dddddd", "#f8d9ab", "#f49911", "#e37639", "#df6c4a", "#cf4132"]
216
+ };
217
+ var BASE_HUE = 28;
218
+ var LEVEL_HUES = [BASE_HUE, 50, 125, 175, 210, 240, 275, 320, 355, 45];
219
+ var NAMES = [
220
+ { en: "Cool Catalyst", cz: "Klidn\xFD katalyz\xE1tor" },
221
+ { en: "Swift Starter", cz: "Svi\u017En\xFD start\xE9r" },
222
+ { en: "Bold Builder", cz: "Bystr\xFD budovatel" },
223
+ { en: "Word Wrangler", cz: "Slovn\xED sb\u011Bratel" },
224
+ { en: "Fluent Flame", cz: "Plynul\xFD plamen" },
225
+ { en: "Mighty Master", cz: "Mocn\xFD mistr" },
226
+ { en: "Radiant Rockstar", cz: "Z\xE1\u0159iv\xFD znalec" },
227
+ { en: "Wise Wizard", cz: "Moudr\xFD m\xE1g" },
228
+ { en: "Legendary Linguist", cz: "Legend\xE1rn\xED lingvista" },
229
+ { en: "Absolute Alpha", cz: "Absolutn\xED alfa" }
230
+ ];
231
+ var PRESETS = [
232
+ "coolCatalyst" /* COOL_CATALYST */,
233
+ "swiftStarter" /* SWIFT_STARTER */,
234
+ "boldBuilder" /* BOLD_BUILDER */,
235
+ "wordWrangler" /* WORD_WRANGLER */,
236
+ "fluentFlame" /* FLUENT_FLAME */,
237
+ "mightyMaster" /* MIGHTY_MASTER */,
238
+ "radiantRockstar" /* RADIANT_ROCKSTAR */,
239
+ "wiseWizard" /* WISE_WIZARD */,
240
+ "legendaryLinguist" /* LEGENDARY_LINGUIST */,
241
+ "absoluteAlpha" /* ABSOLUTE_ALPHA */
242
+ ];
243
+ var generatePalette = (hue) => {
244
+ const shift = hue - BASE_HUE;
245
+ const rotate = (hex) => shiftHue(hex, shift);
246
+ const lightnessFix = hue >= 40 && hue <= 70 ? -0.08 : 0;
247
+ const accent = (s, l) => hslToHex({ h: hue, s, l: l + lightnessFix });
248
+ const isOriginal = shift === 0;
249
+ return {
250
+ background: rotate(DESIGN.background),
251
+ card: rotate(DESIGN.card),
252
+ brand: rotate(DESIGN.brand),
253
+ brandMid: rotate(DESIGN.brandMid),
254
+ brandLight: rotate(DESIGN.brandLight),
255
+ brandPale: rotate(DESIGN.brandPale),
256
+ points: rotate(DESIGN.points),
257
+ streak: rotate(DESIGN.streak),
258
+ test: rotate(DESIGN.test),
259
+ testDark: rotate(DESIGN.testDark),
260
+ testText: rotate(DESIGN.testText),
261
+ // level 1 keeps the original design's exact accent orange and progress track
262
+ accent: isOriginal ? "#e37639" : accent(0.75, 0.5),
263
+ accentDark: accent(0.7, 0.33),
264
+ accentLight: accent(0.9, 0.72),
265
+ accentPale: isOriginal ? "#f2e1d4" : accent(0.85, 0.93),
266
+ chartRetired: accent(0.7, 0.33),
267
+ chartLearning: isOriginal ? "#e37639" : accent(0.75, 0.5),
268
+ chartQueued: accent(0.9, 0.72),
269
+ leaderboardHighlight: rotate(DESIGN.leaderboardHighlight),
270
+ divider: rotate(DESIGN.divider),
271
+ heatScale: DESIGN.heatScale.map(rotate),
272
+ celebrationGradient: [accent(0.9, 0.96), accent(0.85, 0.84), accent(0.8, 0.68)],
273
+ iconHueShift: shift
274
+ };
275
+ };
276
+ var DEFAULT_LEVEL_DEFINITIONS = LEVELS.map((rules, i) => ({
277
+ level: rules.level,
278
+ xpThreshold: rules.xpThreshold,
279
+ minBestStreak: rules.minBestStreak,
280
+ names: NAMES[i],
281
+ palette: generatePalette(LEVEL_HUES[i]),
282
+ avatar: {
283
+ alphaHueShift: LEVEL_HUES[i] - BASE_HUE,
284
+ preset: { id: PRESETS[i], params: { speed: 1 } }
285
+ }
286
+ }));
287
+ var DEFAULT_LEVELS_CONFIG = {
288
+ version: 0,
289
+ levels: DEFAULT_LEVEL_DEFINITIONS,
290
+ awards: DEFAULT_XP_AWARDS
291
+ };
292
+
293
+ // src/concrete/levelValidation.ts
294
+ var MAX_LOTTIE_BYTES = 512 * 1024;
295
+ var MAX_SVG_BYTES = 128 * 1024;
296
+ var MAX_LEVEL_NAME_LENGTH = 40;
297
+ var PALETTE_COLOUR_KEYS = [
298
+ "background",
299
+ "card",
300
+ "brand",
301
+ "brandMid",
302
+ "brandLight",
303
+ "brandPale",
304
+ "points",
305
+ "streak",
306
+ "test",
307
+ "testDark",
308
+ "testText",
309
+ "accent",
310
+ "accentDark",
311
+ "accentLight",
312
+ "accentPale",
313
+ "chartRetired",
314
+ "chartLearning",
315
+ "chartQueued",
316
+ "leaderboardHighlight",
317
+ "divider"
318
+ ];
319
+ var isNonNegativeInt = (value) => Number.isInteger(value) && value >= 0;
320
+ var validateLevelDefinition = (level) => {
321
+ var _a, _b;
322
+ const errors = [];
323
+ const where = `level ${level == null ? void 0 : level.level}`;
324
+ if (!Number.isInteger(level == null ? void 0 : level.level) || level.level < 1) errors.push(`${where}: level must be a whole number from 1`);
325
+ if (!isNonNegativeInt(level == null ? void 0 : level.xpThreshold)) errors.push(`${where}: XP threshold must be a whole number from 0`);
326
+ if (!isNonNegativeInt(level == null ? void 0 : level.minBestStreak)) errors.push(`${where}: best streak must be a whole number from 0`);
327
+ for (const lang of ["en", "cz"]) {
328
+ const name = (_a = level == null ? void 0 : level.names) == null ? void 0 : _a[lang];
329
+ if (typeof name !== "string" || !name.trim() || name.length > MAX_LEVEL_NAME_LENGTH) {
330
+ errors.push(`${where}: ${lang} name must be 1-${MAX_LEVEL_NAME_LENGTH} characters`);
331
+ }
332
+ }
333
+ const palette = level == null ? void 0 : level.palette;
334
+ if (!palette) {
335
+ errors.push(`${where}: palette missing`);
336
+ } else {
337
+ for (const key of PALETTE_COLOUR_KEYS) {
338
+ if (!isHexColor(palette[key])) errors.push(`${where}: palette ${key} must be a hex colour`);
339
+ }
340
+ if (!Array.isArray(palette.heatScale) || palette.heatScale.length !== 6 || !palette.heatScale.every(isHexColor)) {
341
+ errors.push(`${where}: palette heatScale must be 6 hex colours`);
342
+ }
343
+ if (!Array.isArray(palette.celebrationGradient) || palette.celebrationGradient.length !== 3 || !palette.celebrationGradient.every(isHexColor)) {
344
+ errors.push(`${where}: palette celebrationGradient must be 3 hex colours`);
345
+ }
346
+ if (typeof palette.iconHueShift !== "number" || !isFinite(palette.iconHueShift)) {
347
+ errors.push(`${where}: palette iconHueShift must be a number`);
348
+ }
349
+ }
350
+ const avatar = level == null ? void 0 : level.avatar;
351
+ if (!avatar || typeof avatar.alphaHueShift !== "number" || !isFinite(avatar.alphaHueShift)) {
352
+ errors.push(`${where}: avatar alphaHueShift must be a number`);
353
+ } else {
354
+ if (avatar.preset && !Object.values(AvatarPresetId).includes(avatar.preset.id)) {
355
+ errors.push(`${where}: unknown avatar preset '${avatar.preset.id}'`);
356
+ }
357
+ if (avatar.lottie !== void 0) {
358
+ if (typeof avatar.lottie !== "string" || avatar.lottie.length > MAX_LOTTIE_BYTES) {
359
+ errors.push(`${where}: Lottie animation must be at most ${MAX_LOTTIE_BYTES / 1024}KB`);
360
+ } else {
361
+ try {
362
+ JSON.parse(avatar.lottie);
363
+ } catch (e) {
364
+ errors.push(`${where}: Lottie animation is not valid JSON`);
365
+ }
366
+ }
367
+ }
368
+ for (const image of (_b = avatar.images) != null ? _b : []) {
369
+ if (typeof (image == null ? void 0 : image.svg) !== "string" || !image.svg.includes("<svg") || image.svg.length > MAX_SVG_BYTES) {
370
+ errors.push(`${where}: image '${image == null ? void 0 : image.id}' must be SVG markup of at most ${MAX_SVG_BYTES / 1024}KB`);
371
+ }
372
+ }
373
+ }
374
+ return errors;
375
+ };
376
+ var validateXpAwards = (awards) => ["flashcardReview", "test", "perTestKnownAnswer", "perWordRetired", "dailyStreakBonusCap"].filter((key) => !isNonNegativeInt(awards == null ? void 0 : awards[key])).map((key) => `XP award ${key} must be a whole number from 0`);
377
+ var validateLevelsConfig = (config) => {
378
+ var _a;
379
+ const errors = validateXpAwards(config.awards);
380
+ const levels = [...(_a = config.levels) != null ? _a : []].sort((a, b) => a.level - b.level);
381
+ if (levels.length === 0) return [...errors, "there must be at least one level"];
382
+ levels.forEach((level, i) => {
383
+ errors.push(...validateLevelDefinition(level));
384
+ if (level.level !== i + 1) errors.push(`levels must be numbered 1 to ${levels.length} with no gaps`);
385
+ if (i === 0 && level.xpThreshold !== 0) errors.push("level 1 must need 0 XP");
386
+ if (i > 0 && level.xpThreshold <= levels[i - 1].xpThreshold) {
387
+ errors.push(`level ${level.level} must need more XP than level ${levels[i - 1].level}`);
388
+ }
389
+ if (i > 0 && level.minBestStreak < levels[i - 1].minBestStreak) {
390
+ errors.push(`level ${level.level} can't need a shorter best streak than level ${levels[i - 1].level}`);
391
+ }
392
+ });
393
+ return [...new Set(errors)];
394
+ };
395
+
64
396
  // src/design/types.ts
65
397
  var Language = /* @__PURE__ */ ((Language2) => {
66
398
  Language2["CZECH"] = "CZECH";
@@ -257,6 +589,7 @@ var ApiPath = /* @__PURE__ */ ((ApiPath2) => {
257
589
  ApiPath2["HEALTH"] = "/health";
258
590
  ApiPath2["LAST_WORDS_ADDED"] = "/lastWordsAdded";
259
591
  ApiPath2["LEADERBOARD"] = "/leaderboard";
592
+ ApiPath2["LEVELS"] = "/levels";
260
593
  ApiPath2["LEXEMES"] = "/lexemes";
261
594
  ApiPath2["LEXEMES_ALL"] = "/lexemes/all";
262
595
  ApiPath2["LEXEMES_COUNT"] = "/lexemes/count/:language";
@@ -294,32 +627,60 @@ export {
294
627
  ApiMethod,
295
628
  ApiPath,
296
629
  AppError,
630
+ AvatarPresetId,
297
631
  ClientPlatform,
632
+ DEFAULT_LEVELS_CONFIG,
633
+ DEFAULT_LEVEL_DEFINITIONS,
634
+ DEFAULT_XP_AWARDS,
298
635
  Familiarity,
299
636
  HttpStatusCode,
300
637
  LEARNING_STAGES_IN_GROUP,
638
+ LEVELS,
301
639
  Language,
302
640
  LearningStage,
303
641
  LearningStageGroup,
304
642
  Lexeme,
305
643
  LexemePair,
644
+ MAX_LEVEL_NAME_LENGTH,
645
+ MAX_LOTTIE_BYTES,
646
+ MAX_SVG_BYTES,
306
647
  Progress,
307
648
  ReminderFrequency,
308
649
  Scenario,
309
650
  VocabCheckType,
651
+ XP_DAILY_STREAK_BONUS_CAP,
652
+ XP_FLASHCARD_REVIEW,
653
+ XP_PER_TEST_KNOWN_ANSWER,
654
+ XP_PER_WORD_RETIRED,
655
+ XP_TEST,
310
656
  convertJSDateStringToMySQLDate,
311
657
  dateDifferenceInDays,
312
658
  deriveStreakFromVocabCheckActivity,
659
+ generatePalette,
660
+ getBestStreak,
661
+ getFlashcardReviewXp,
313
662
  getFormattedDate,
663
+ getLevel,
664
+ getLevelProgress,
314
665
  getMysqlDateIgnoreTZ,
666
+ getTestXp,
667
+ getUserLevelProgress,
668
+ hexToHsl,
669
+ hslToHex,
315
670
  isClientDateTooFarFromServerDate,
316
671
  isExpired,
317
672
  isFinalTest,
673
+ isHexColor,
318
674
  isLearningStageGroup,
319
675
  isStringContainingInteger,
320
676
  isThePreviousDay,
321
677
  isTheSameDay,
322
678
  isValidJsDateString,
323
679
  isValidMysqlDateString,
324
- parameterReplace
680
+ maxLevel,
681
+ parameterReplace,
682
+ shiftHue,
683
+ validateLevelDefinition,
684
+ validateLevelsConfig,
685
+ validateXpAwards
325
686
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "czapp-shared",
3
- "version": "1.0.38",
3
+ "version": "1.1.0",
4
4
  "description": "This is a shared library for Czapp projects. It contains common code that is used across multiple projects.",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -0,0 +1,41 @@
1
+ // Colour helpers - hex <-> HSL and hue rotation, used to build level palettes (see levelDefaults.ts).
2
+
3
+ export type Hsl = { h: number, s: number, l: number };
4
+
5
+ export const hexToHsl = (hex: string): Hsl => {
6
+ let value = hex.replace('#', '');
7
+ if (value.length === 3) value = value.split('').map((c) => c + c).join('');
8
+ const r = parseInt(value.slice(0, 2), 16) / 255;
9
+ const g = parseInt(value.slice(2, 4), 16) / 255;
10
+ const b = parseInt(value.slice(4, 6), 16) / 255;
11
+ const max = Math.max(r, g, b);
12
+ const min = Math.min(r, g, b);
13
+ const l = (max + min) / 2;
14
+ if (max === min) return { h: 0, s: 0, l };
15
+ const d = max - min;
16
+ const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
17
+ const h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
18
+ return { h: h * 60, s, l };
19
+ };
20
+
21
+ export const hslToHex = ({ h, s, l }: Hsl): string => {
22
+ const hue = ((h % 360) + 360) % 360;
23
+ const c = (1 - Math.abs(2 * l - 1)) * s;
24
+ const x = c * (1 - Math.abs(((hue / 60) % 2) - 1));
25
+ const m = l - c / 2;
26
+ const [r, g, b] =
27
+ hue < 60 ? [c, x, 0] : hue < 120 ? [x, c, 0] : hue < 180 ? [0, c, x] :
28
+ hue < 240 ? [0, x, c] : hue < 300 ? [x, 0, c] : [c, 0, x];
29
+ const toHex = (v: number) => Math.round((v + m) * 255).toString(16).padStart(2, '0');
30
+ return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
31
+ };
32
+
33
+ // rotates a colour round the colour wheel, keeping its saturation and lightness (so greys and whites barely change)
34
+ export const shiftHue = (hex: string, degrees: number): string => {
35
+ if (!degrees) return hex;
36
+ const hsl = hexToHsl(hex);
37
+ return hslToHex({ ...hsl, h: hsl.h + degrees });
38
+ };
39
+
40
+ export const isHexColor = (value: unknown): value is string =>
41
+ typeof value === 'string' && /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value);
@@ -0,0 +1,144 @@
1
+ /**
2
+ * XP and experience levels.
3
+ *
4
+ * XP vs reward points - two separate running totals on the user, both updated by /test/complete:
5
+ *
6
+ * Reward points (IUserData.rewardPoints)
7
+ * - Measure PERFORMANCE: points per word known, plus bonuses for high scores in a session.
8
+ * - Shown to the user (home screen Reward Points card) and ranked on the leaderboard.
9
+ *
10
+ * XP (IUserData.xp)
11
+ * - Measure ENGAGEMENT and PROGRESS: doing reviews and tests at all, mastering (retiring) words, keeping a
12
+ * daily streak. A weak session still earns XP; scores barely matter.
13
+ * - Internal only: NEVER shown to the user, who would confuse it with reward points. Its sole purpose is to
14
+ * decide the user's experience level (the level name and alpha artwork on the home screen).
15
+ *
16
+ * Never derive one from the other, and don't show XP numbers in the app - show the level and progress towards the
17
+ * next one instead.
18
+ *
19
+ * A user's level is derived from their XP and their best streak - it is never stored, so client and server can't
20
+ * disagree, and because neither value ever decreases, a level once reached is never lost.
21
+ */
22
+
23
+ import { IXpAwards } from '../design/levels';
24
+
25
+ export const XP_FLASHCARD_REVIEW = 10;
26
+ export const XP_TEST = 15;
27
+ export const XP_PER_TEST_KNOWN_ANSWER = 1;
28
+ export const XP_PER_WORD_RETIRED = 5;
29
+ // The first review of each streak day earns XP equal to the streak length, capped here.
30
+ export const XP_DAILY_STREAK_BONUS_CAP = 30;
31
+
32
+ export interface ILevel {
33
+ // 1-based
34
+ level: number;
35
+ xpThreshold: number;
36
+ // Best streak (days) also needed to reach this level, so it can't be reached by grinding in one burst.
37
+ minBestStreak: number;
38
+ }
39
+
40
+ export const LEVELS: readonly ILevel[] = [
41
+ { level: 1, xpThreshold: 0, minBestStreak: 0 },
42
+ { level: 2, xpThreshold: 60, minBestStreak: 0 },
43
+ { level: 3, xpThreshold: 200, minBestStreak: 0 },
44
+ { level: 4, xpThreshold: 450, minBestStreak: 0 },
45
+ { level: 5, xpThreshold: 900, minBestStreak: 7 },
46
+ { level: 6, xpThreshold: 1600, minBestStreak: 14 },
47
+ { level: 7, xpThreshold: 2700, minBestStreak: 21 },
48
+ { level: 8, xpThreshold: 4300, minBestStreak: 30 },
49
+ { level: 9, xpThreshold: 6500, minBestStreak: 45 },
50
+ { level: 10, xpThreshold: 10000, minBestStreak: 60 },
51
+ ];
52
+
53
+ export const maxLevel = LEVELS[LEVELS.length - 1].level;
54
+
55
+ const meetsRequirements = (level: ILevel, xp: number, bestStreak: number): boolean =>
56
+ xp >= level.xpThreshold && bestStreak >= level.minBestStreak;
57
+
58
+ // levels may come from the database (Level Designer) in any order - work on them sorted by level number
59
+ const sorted = (levels: readonly ILevel[]): readonly ILevel[] =>
60
+ levels.length < 2 || levels.every((l, i) => i === 0 || levels[i - 1].level < l.level)
61
+ ? levels
62
+ : [...levels].sort((a, b) => a.level - b.level);
63
+
64
+ /**
65
+ * @name getLevel
66
+ * @description The highest level whose XP threshold and best-streak requirement are both met. Levels must be
67
+ * reached in order, so a missing streak for level 5 holds the user at level 4 however much XP they have.
68
+ * @param levels - the level rules, e.g. the published ILevelsConfig levels; defaults to the built-in LEVELS
69
+ */
70
+ export const getLevel = (xp: number, bestStreak: number, levels: readonly ILevel[] = LEVELS): number => {
71
+ const ordered = sorted(levels);
72
+ let reached = ordered[0]?.level ?? 1;
73
+ for (const level of ordered) {
74
+ if (!meetsRequirements(level, xp, bestStreak)) {
75
+ break;
76
+ }
77
+ reached = level.level;
78
+ }
79
+ return reached;
80
+ };
81
+
82
+ export interface ILevelProgress {
83
+ level: number;
84
+ // undefined at the top level
85
+ nextLevel?: number;
86
+ // XP still needed for the next level (0 when only the streak is missing)
87
+ xpToNextLevel: number;
88
+ // 0..1 through the XP between this level's threshold and the next one's
89
+ xpProgress: number;
90
+ // Best streak still needed for the next level (0 when it's already met)
91
+ streakDaysToNextLevel: number;
92
+ }
93
+
94
+ export const getLevelProgress = (xp: number, bestStreak: number, levels: readonly ILevel[] = LEVELS): ILevelProgress => {
95
+ const ordered = sorted(levels);
96
+ const level = getLevel(xp, bestStreak, ordered);
97
+ const index = ordered.findIndex((l) => l.level === level);
98
+ const current = ordered[index];
99
+ const next = ordered[index + 1];
100
+ if (!current || !next) {
101
+ return { level, xpToNextLevel: 0, xpProgress: 1, streakDaysToNextLevel: 0 };
102
+ }
103
+ const span = Math.max(1, next.xpThreshold - current.xpThreshold);
104
+ return {
105
+ level,
106
+ nextLevel: next.level,
107
+ xpToNextLevel: Math.max(0, next.xpThreshold - xp),
108
+ xpProgress: Math.min(1, Math.max(0, (xp - current.xpThreshold) / span)),
109
+ streakDaysToNextLevel: Math.max(0, next.minBestStreak - bestStreak),
110
+ };
111
+ };
112
+
113
+ // the built-in XP awards - the Level Designer can override them (ILevelsConfig.awards)
114
+ export const DEFAULT_XP_AWARDS: IXpAwards = {
115
+ flashcardReview: XP_FLASHCARD_REVIEW,
116
+ test: XP_TEST,
117
+ perTestKnownAnswer: XP_PER_TEST_KNOWN_ANSWER,
118
+ perWordRetired: XP_PER_WORD_RETIRED,
119
+ dailyStreakBonusCap: XP_DAILY_STREAK_BONUS_CAP,
120
+ };
121
+
122
+ /**
123
+ * @name getFlashcardReviewXp
124
+ * @param retiredCount - words promoted to RETIRED (mastered) by this review
125
+ * @param newStreakDayLength - the streak length if this review is the first of a new streak day, otherwise 0
126
+ * @param awards - the XP award amounts; defaults to the built-in ones
127
+ */
128
+ export const getFlashcardReviewXp = (retiredCount: number, newStreakDayLength: number, awards: IXpAwards = DEFAULT_XP_AWARDS): number =>
129
+ awards.flashcardReview
130
+ + retiredCount * awards.perWordRetired
131
+ + Math.min(Math.max(0, newStreakDayLength), awards.dailyStreakBonusCap);
132
+
133
+ export const getTestXp = (knownCount: number, awards: IXpAwards = DEFAULT_XP_AWARDS): number =>
134
+ awards.test + knownCount * awards.perTestKnownAnswer;
135
+
136
+ // highStreakLength can lag a still-running current streak (the leaderboard has the same caveat), so take the larger.
137
+ export const getBestStreak = (user: { highStreakLength: number, currentStreakLength: number }): number =>
138
+ Math.max(user.highStreakLength ?? 0, user.currentStreakLength ?? 0);
139
+
140
+ export const getUserLevelProgress = (
141
+ user: { xp: number, highStreakLength: number, currentStreakLength: number },
142
+ levels: readonly ILevel[] = LEVELS,
143
+ ): ILevelProgress =>
144
+ getLevelProgress(user.xp ?? 0, getBestStreak(user), levels);