czapp-shared 1.0.39 → 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;
@@ -81,9 +133,12 @@ var LEVELS = [
81
133
  ];
82
134
  var maxLevel = LEVELS[LEVELS.length - 1].level;
83
135
  var meetsRequirements = (level, xp, bestStreak) => xp >= level.xpThreshold && bestStreak >= level.minBestStreak;
84
- var getLevel = (xp, bestStreak) => {
85
- let reached = LEVELS[0].level;
86
- for (const level of LEVELS) {
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) {
87
142
  if (!meetsRequirements(level, xp, bestStreak)) {
88
143
  break;
89
144
  }
@@ -91,14 +146,16 @@ var getLevel = (xp, bestStreak) => {
91
146
  }
92
147
  return reached;
93
148
  };
94
- var getLevelProgress = (xp, bestStreak) => {
95
- const level = getLevel(xp, bestStreak);
96
- const current = LEVELS[level - 1];
97
- const next = LEVELS[level];
98
- if (!next) {
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) {
99
156
  return { level, xpToNextLevel: 0, xpProgress: 1, streakDaysToNextLevel: 0 };
100
157
  }
101
- const span = next.xpThreshold - current.xpThreshold;
158
+ const span = Math.max(1, next.xpThreshold - current.xpThreshold);
102
159
  return {
103
160
  level,
104
161
  nextLevel: next.level,
@@ -107,15 +164,233 @@ var getLevelProgress = (xp, bestStreak) => {
107
164
  streakDaysToNextLevel: Math.max(0, next.minBestStreak - bestStreak)
108
165
  };
109
166
  };
110
- var getFlashcardReviewXp = (retiredCount, newStreakDayLength) => XP_FLASHCARD_REVIEW + retiredCount * XP_PER_WORD_RETIRED + Math.min(Math.max(0, newStreakDayLength), XP_DAILY_STREAK_BONUS_CAP);
111
- var getTestXp = (knownCount) => XP_TEST + knownCount * XP_PER_TEST_KNOWN_ANSWER;
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;
112
176
  var getBestStreak = (user) => {
113
177
  var _a, _b;
114
178
  return Math.max((_a = user.highStreakLength) != null ? _a : 0, (_b = user.currentStreakLength) != null ? _b : 0);
115
179
  };
116
- var getUserLevelProgress = (user) => {
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) => {
117
378
  var _a;
118
- return getLevelProgress((_a = user.xp) != null ? _a : 0, getBestStreak(user));
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)];
119
394
  };
120
395
 
121
396
  // src/design/types.ts
@@ -314,6 +589,7 @@ var ApiPath = /* @__PURE__ */ ((ApiPath2) => {
314
589
  ApiPath2["HEALTH"] = "/health";
315
590
  ApiPath2["LAST_WORDS_ADDED"] = "/lastWordsAdded";
316
591
  ApiPath2["LEADERBOARD"] = "/leaderboard";
592
+ ApiPath2["LEVELS"] = "/levels";
317
593
  ApiPath2["LEXEMES"] = "/lexemes";
318
594
  ApiPath2["LEXEMES_ALL"] = "/lexemes/all";
319
595
  ApiPath2["LEXEMES_COUNT"] = "/lexemes/count/:language";
@@ -351,7 +627,11 @@ export {
351
627
  ApiMethod,
352
628
  ApiPath,
353
629
  AppError,
630
+ AvatarPresetId,
354
631
  ClientPlatform,
632
+ DEFAULT_LEVELS_CONFIG,
633
+ DEFAULT_LEVEL_DEFINITIONS,
634
+ DEFAULT_XP_AWARDS,
355
635
  Familiarity,
356
636
  HttpStatusCode,
357
637
  LEARNING_STAGES_IN_GROUP,
@@ -361,6 +641,9 @@ export {
361
641
  LearningStageGroup,
362
642
  Lexeme,
363
643
  LexemePair,
644
+ MAX_LEVEL_NAME_LENGTH,
645
+ MAX_LOTTIE_BYTES,
646
+ MAX_SVG_BYTES,
364
647
  Progress,
365
648
  ReminderFrequency,
366
649
  Scenario,
@@ -373,6 +656,7 @@ export {
373
656
  convertJSDateStringToMySQLDate,
374
657
  dateDifferenceInDays,
375
658
  deriveStreakFromVocabCheckActivity,
659
+ generatePalette,
376
660
  getBestStreak,
377
661
  getFlashcardReviewXp,
378
662
  getFormattedDate,
@@ -381,9 +665,12 @@ export {
381
665
  getMysqlDateIgnoreTZ,
382
666
  getTestXp,
383
667
  getUserLevelProgress,
668
+ hexToHsl,
669
+ hslToHex,
384
670
  isClientDateTooFarFromServerDate,
385
671
  isExpired,
386
672
  isFinalTest,
673
+ isHexColor,
387
674
  isLearningStageGroup,
388
675
  isStringContainingInteger,
389
676
  isThePreviousDay,
@@ -391,5 +678,9 @@ export {
391
678
  isValidJsDateString,
392
679
  isValidMysqlDateString,
393
680
  maxLevel,
394
- parameterReplace
681
+ parameterReplace,
682
+ shiftHue,
683
+ validateLevelDefinition,
684
+ validateLevelsConfig,
685
+ validateXpAwards
395
686
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "czapp-shared",
3
- "version": "1.0.39",
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);
@@ -20,6 +20,8 @@
20
20
  * disagree, and because neither value ever decreases, a level once reached is never lost.
21
21
  */
22
22
 
23
+ import { IXpAwards } from '../design/levels';
24
+
23
25
  export const XP_FLASHCARD_REVIEW = 10;
24
26
  export const XP_TEST = 15;
25
27
  export const XP_PER_TEST_KNOWN_ANSWER = 1;
@@ -53,14 +55,22 @@ export const maxLevel = LEVELS[LEVELS.length - 1].level;
53
55
  const meetsRequirements = (level: ILevel, xp: number, bestStreak: number): boolean =>
54
56
  xp >= level.xpThreshold && bestStreak >= level.minBestStreak;
55
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
+
56
64
  /**
57
65
  * @name getLevel
58
66
  * @description The highest level whose XP threshold and best-streak requirement are both met. Levels must be
59
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
60
69
  */
61
- export const getLevel = (xp: number, bestStreak: number): number => {
62
- let reached = LEVELS[0].level;
63
- for (const level of LEVELS) {
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) {
64
74
  if (!meetsRequirements(level, xp, bestStreak)) {
65
75
  break;
66
76
  }
@@ -81,14 +91,16 @@ export interface ILevelProgress {
81
91
  streakDaysToNextLevel: number;
82
92
  }
83
93
 
84
- export const getLevelProgress = (xp: number, bestStreak: number): ILevelProgress => {
85
- const level = getLevel(xp, bestStreak);
86
- const current = LEVELS[level - 1];
87
- const next = LEVELS[level];
88
- if (!next) {
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) {
89
101
  return { level, xpToNextLevel: 0, xpProgress: 1, streakDaysToNextLevel: 0 };
90
102
  }
91
- const span = next.xpThreshold - current.xpThreshold;
103
+ const span = Math.max(1, next.xpThreshold - current.xpThreshold);
92
104
  return {
93
105
  level,
94
106
  nextLevel: next.level,
@@ -98,22 +110,35 @@ export const getLevelProgress = (xp: number, bestStreak: number): ILevelProgress
98
110
  };
99
111
  };
100
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
+
101
122
  /**
102
123
  * @name getFlashcardReviewXp
103
124
  * @param retiredCount - words promoted to RETIRED (mastered) by this review
104
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
105
127
  */
106
- export const getFlashcardReviewXp = (retiredCount: number, newStreakDayLength: number): number =>
107
- XP_FLASHCARD_REVIEW
108
- + retiredCount * XP_PER_WORD_RETIRED
109
- + Math.min(Math.max(0, newStreakDayLength), XP_DAILY_STREAK_BONUS_CAP);
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);
110
132
 
111
- export const getTestXp = (knownCount: number): number =>
112
- XP_TEST + knownCount * XP_PER_TEST_KNOWN_ANSWER;
133
+ export const getTestXp = (knownCount: number, awards: IXpAwards = DEFAULT_XP_AWARDS): number =>
134
+ awards.test + knownCount * awards.perTestKnownAnswer;
113
135
 
114
136
  // highStreakLength can lag a still-running current streak (the leaderboard has the same caveat), so take the larger.
115
137
  export const getBestStreak = (user: { highStreakLength: number, currentStreakLength: number }): number =>
116
138
  Math.max(user.highStreakLength ?? 0, user.currentStreakLength ?? 0);
117
139
 
118
- export const getUserLevelProgress = (user: { xp: number, highStreakLength: number, currentStreakLength: number }): ILevelProgress =>
119
- getLevelProgress(user.xp ?? 0, getBestStreak(user));
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);
@@ -0,0 +1,118 @@
1
+ import { AvatarPresetId, ILevelDefinition, ILevelPalette, ILevelsConfig } from '../design/levels';
2
+ import { hslToHex, shiftHue } from './color';
3
+ import { DEFAULT_XP_AWARDS, LEVELS } from './level';
4
+
5
+ /**
6
+ * The built-in level definitions: what the apps show when no published configuration has been loaded (offline, first
7
+ * launch), and what the czapp-server xp_levels table is seeded with. They reproduce the original hard-coded levels:
8
+ * level 1 is the app's original orange design; each later level rotates it round the colour wheel to its own hue.
9
+ */
10
+
11
+ // the original design's colours (level 1)
12
+ const DESIGN = {
13
+ background: '#ece7e1',
14
+ card: '#f9f8f6',
15
+ brand: '#317a97',
16
+ brandMid: '#76b2cb',
17
+ brandLight: '#a7d2e4',
18
+ brandPale: '#cedfe8',
19
+ points: '#fcb64a',
20
+ streak: '#f0643f',
21
+ test: '#80bda6',
22
+ testDark: '#326451',
23
+ testText: '#4c836e',
24
+ leaderboardHighlight: '#fbe6c4',
25
+ divider: '#d9d3c9',
26
+ heatScale: ['#dddddd', '#f8d9ab', '#f49911', '#e37639', '#df6c4a', '#cf4132'],
27
+ };
28
+
29
+ // hue of the alpha logo's main orange (#f5831f) - level 1's hue
30
+ const BASE_HUE = 28;
31
+
32
+ // each level's hue: orange (the original design), then on round the colour wheel; level 10 is gold
33
+ const LEVEL_HUES = [BASE_HUE, 50, 125, 175, 210, 240, 275, 320, 355, 45];
34
+
35
+ const NAMES: { en: string, cz: string }[] = [
36
+ { en: 'Cool Catalyst', cz: 'Klidný katalyzátor' },
37
+ { en: 'Swift Starter', cz: 'Svižný startér' },
38
+ { en: 'Bold Builder', cz: 'Bystrý budovatel' },
39
+ { en: 'Word Wrangler', cz: 'Slovní sběratel' },
40
+ { en: 'Fluent Flame', cz: 'Plynulý plamen' },
41
+ { en: 'Mighty Master', cz: 'Mocný mistr' },
42
+ { en: 'Radiant Rockstar', cz: 'Zářivý znalec' },
43
+ { en: 'Wise Wizard', cz: 'Moudrý mág' },
44
+ { en: 'Legendary Linguist', cz: 'Legendární lingvista' },
45
+ { en: 'Absolute Alpha', cz: 'Absolutní alfa' },
46
+ ];
47
+
48
+ const PRESETS: AvatarPresetId[] = [
49
+ AvatarPresetId.COOL_CATALYST,
50
+ AvatarPresetId.SWIFT_STARTER,
51
+ AvatarPresetId.BOLD_BUILDER,
52
+ AvatarPresetId.WORD_WRANGLER,
53
+ AvatarPresetId.FLUENT_FLAME,
54
+ AvatarPresetId.MIGHTY_MASTER,
55
+ AvatarPresetId.RADIANT_ROCKSTAR,
56
+ AvatarPresetId.WISE_WIZARD,
57
+ AvatarPresetId.LEGENDARY_LINGUIST,
58
+ AvatarPresetId.ABSOLUTE_ALPHA,
59
+ ];
60
+
61
+ /**
62
+ * A full palette generated from one hue: the original design rotated round the colour wheel by (hue - level 1's
63
+ * hue), with the level's accent shades derived from the hue itself. The Level Designer's "generate from hue" uses
64
+ * this as a starting point.
65
+ */
66
+ export const generatePalette = (hue: number): ILevelPalette => {
67
+ const shift = hue - BASE_HUE;
68
+ const rotate = (hex: string) => shiftHue(hex, shift);
69
+ // yellow-ish hues read too light at the usual lightness, so darken them a little
70
+ const lightnessFix = hue >= 40 && hue <= 70 ? -0.08 : 0;
71
+ const accent = (s: number, l: number) => hslToHex({ h: hue, s, l: l + lightnessFix });
72
+ const isOriginal = shift === 0;
73
+ return {
74
+ background: rotate(DESIGN.background),
75
+ card: rotate(DESIGN.card),
76
+ brand: rotate(DESIGN.brand),
77
+ brandMid: rotate(DESIGN.brandMid),
78
+ brandLight: rotate(DESIGN.brandLight),
79
+ brandPale: rotate(DESIGN.brandPale),
80
+ points: rotate(DESIGN.points),
81
+ streak: rotate(DESIGN.streak),
82
+ test: rotate(DESIGN.test),
83
+ testDark: rotate(DESIGN.testDark),
84
+ testText: rotate(DESIGN.testText),
85
+ // level 1 keeps the original design's exact accent orange and progress track
86
+ accent: isOriginal ? '#e37639' : accent(0.75, 0.5),
87
+ accentDark: accent(0.7, 0.33),
88
+ accentLight: accent(0.9, 0.72),
89
+ accentPale: isOriginal ? '#f2e1d4' : accent(0.85, 0.93),
90
+ chartRetired: accent(0.7, 0.33),
91
+ chartLearning: isOriginal ? '#e37639' : accent(0.75, 0.5),
92
+ chartQueued: accent(0.9, 0.72),
93
+ leaderboardHighlight: rotate(DESIGN.leaderboardHighlight),
94
+ divider: rotate(DESIGN.divider),
95
+ heatScale: DESIGN.heatScale.map(rotate) as ILevelPalette['heatScale'],
96
+ celebrationGradient: [accent(0.9, 0.96), accent(0.85, 0.84), accent(0.8, 0.68)],
97
+ iconHueShift: shift,
98
+ };
99
+ };
100
+
101
+ export const DEFAULT_LEVEL_DEFINITIONS: ILevelDefinition[] = LEVELS.map((rules, i) => ({
102
+ level: rules.level,
103
+ xpThreshold: rules.xpThreshold,
104
+ minBestStreak: rules.minBestStreak,
105
+ names: NAMES[i],
106
+ palette: generatePalette(LEVEL_HUES[i]),
107
+ avatar: {
108
+ alphaHueShift: LEVEL_HUES[i] - BASE_HUE,
109
+ preset: { id: PRESETS[i], params: { speed: 1 } },
110
+ },
111
+ }));
112
+
113
+ // version 0 means "the built-in defaults" - any published configuration has a higher version
114
+ export const DEFAULT_LEVELS_CONFIG: ILevelsConfig = {
115
+ version: 0,
116
+ levels: DEFAULT_LEVEL_DEFINITIONS,
117
+ awards: DEFAULT_XP_AWARDS,
118
+ };