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.d.mts +193 -1
- package/dist/index.d.ts +193 -1
- package/dist/index.js +388 -2
- package/dist/index.mjs +362 -1
- package/package.json +1 -1
- package/src/concrete/color.ts +41 -0
- package/src/concrete/level.ts +144 -0
- package/src/concrete/levelDefaults.ts +118 -0
- package/src/concrete/levelValidation.ts +101 -0
- package/src/design/api.ts +5 -0
- package/src/design/levels.ts +103 -0
- package/src/design/user.ts +5 -1
- package/src/index.ts +5 -0
- package/test/level.test.ts +89 -0
- package/test/levelConfig.test.ts +106 -0
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
|
-
|
|
680
|
+
maxLevel,
|
|
681
|
+
parameterReplace,
|
|
682
|
+
shiftHue,
|
|
683
|
+
validateLevelDefinition,
|
|
684
|
+
validateLevelsConfig,
|
|
685
|
+
validateXpAwards
|
|
325
686
|
};
|
package/package.json
CHANGED
|
@@ -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);
|