@sudobility/sudojo_lib 0.0.201 → 0.0.203

package/dist/utils/date.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.js","sourceRoot":"","sources":["../../src/utils/date.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,YAAY,GAAG,0BAA0B,CAAC;AAEhD,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAa,IAAI,IAAI,EAAE;IACtD,OAAO,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,IAAI,IAAI,CACrE,IAAI,CAAC,UAAU,EAAE,CAClB,EAAE,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAgC;IAEhC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;IAC1B,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,IACE,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC;QAChC,IAAI,CAAC,QAAQ,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;QACjC,IAAI,CAAC,OAAO,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,EAC5B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAmC,EACnC,MAA0B,EAC1B,UAAsC;IACpC,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,SAAS;CACf;IAED,MAAM,UAAU,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAIjD,CAAC;IACF,OAAO,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAoC,EACpC,MAAY,IAAI,IAAI,EAAE;IAEtB,MAAM,UAAU,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACjD,OAAO,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,gBAAgB,CAAC,GAAG,CAAC,CAAC;AACrE,CAAC","sourcesContent":["/**\n * Calendar-date helpers for daily puzzles.\n *\n * A daily's `date` is a calendar date (`YYYY-MM-DD`), not an instant. The API's\n * `/dailies/today` picks the daily by the **UTC** date, so \"today\" for the\n * daily is the UTC date everywhere in the clients.\n */\n\nconst DATE_PATTERN = /^(\\d{4})-(\\d{2})-(\\d{2})/;\n\nfunction pad2(n: number): string {\n  return String(n).padStart(2, '0');\n}\n\n/**\n * The UTC calendar date of `date` (default: now) as `YYYY-MM-DD`, the date\n * the API's `/dailies/today` uses.\n */\nexport function getUtcDateString(date: Date = new Date()): string {\n  return `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(\n    date.getUTCDate()\n  )}`;\n}\n\n/**\n * Normalize a daily date (`YYYY-MM-DD`, or an ISO timestamp starting with\n * one) to `YYYY-MM-DD`, without any timezone shift. Returns null when it does\n * not start with a valid date.\n */\nexport function normalizeDailyDate(\n  value: string | null | undefined\n): string | null {\n  const match = value ? DATE_PATTERN.exec(value) : null;\n  if (!match) return null;\n  const [, y, m, d] = match;\n  const date = new Date(Number(y), Number(m) - 1, Number(d));\n  if (\n    date.getFullYear() !== Number(y) ||\n    date.getMonth() !== Number(m) - 1 ||\n    date.getDate() !== Number(d)\n  ) {\n    return null;\n  }\n  return `${y}-${m}-${d}`;\n}\n\n/**\n * Format a daily's `YYYY-MM-DD` date for display as that LOCAL calendar date\n * (never shifted by the viewer's UTC offset, which `new Date('2026-10-05')`\n * would do west of UTC).\n *\n * @param yyyyMmDd - The daily's date\n * @param locale - BCP 47 locale (default: the runtime's)\n * @param options - Intl options (default: short weekday, short month, day,\n *   e.g. \"Mon, Oct 5\")\n * @returns The formatted date, or null for an invalid date\n */\nexport function formatDailyDate(\n  yyyyMmDd: string | null | undefined,\n  locale?: string | string[],\n  options: Intl.DateTimeFormatOptions = {\n    weekday: 'short',\n    month: 'short',\n    day: 'numeric',\n  }\n): string | null {\n  const normalized = normalizeDailyDate(yyyyMmDd);\n  if (!normalized) return null;\n  const [y, m, d] = normalized.split('-').map(Number) as [\n    number,\n    number,\n    number,\n  ];\n  return new Date(y, m - 1, d).toLocaleDateString(locale, options);\n}\n\n/**\n * Whether a saved daily game is from another day than today's daily\n * (UTC, like the API), so it should be cleared rather than resumed.\n * A missing date counts as stale.\n */\nexport function isStaleDaily(\n  dailyDate: string | null | undefined,\n  now: Date = new Date()\n): boolean {\n  const normalized = normalizeDailyDate(dailyDate);\n  return normalized === null || normalized !== getUtcDateString(now);\n}\n"]}

package/dist/utils/entityTranslate.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Translation of API entities (levels, techniques, badges) in the apps.
+ *
+ * Two key schemes are in use, and this file documents both:
+ *
+ * 1. **API localization keys** (`level.localization.title.stringKey`): dotted
+ *    paths whose first segment names the entity family, e.g. `levels.3.title`,
+ *    `techniques.full-house.title`, `badges.level_1.title`. Resolve them with
+ *    `localizedField(tEntity, ...)` where `tEntity` comes from
+ *    {@link createNamespacedTranslate}.
+ * 2. **Namespace keys** the apps look up directly in an i18next namespace:
+ *    `${level}.title` / `${level}.text` in `levels`, `${path}.title` in
+ *    `techniques`, `${level}.name` / `${level}.label` in `belts`.
+ *
+ * The older helpers in `i18nKeys.ts` (`getLevelKey` → `levels.N`,
+ * `getBeltKey` → `belts.N.name`) build keys for a single merged namespace and
+ * keep that behavior; the display helpers here match what the apps render.
+ */
+import type { LocalizedHint } from '@sudobility/sudojo_types';
+import { type TranslateFunction } from './localizedHint';
+/**
+ * Route entity keys to the i18next namespace that holds them.
+ *
+ * Some families live in their own namespace whose file is NOT nested under the
+ * family segment (`levels.json` is `{ "3": { "title": ... } }`), so a key like
+ * `levels.3.title` only resolves once the prefix is stripped and the lookup is
+ * routed to that namespace. Others (`badges.*`) live nested inside the default
+ * namespace and resolve as-is.
+ *
+ * On a miss the returned function defers to `fallback` with the untouched key,
+ * so callers such as `localizedField` still get the original key back, detect
+ * the miss, and fall back to the raw API value.
+ *
+ * @example
+ * const tEntity = createNamespacedTranslate(tApp, { levels: tLevels, techniques: tTechniques });
+ * localizedField(tEntity, level.localization?.title, level.title);
+ */
+export declare function createNamespacedTranslate(fallback: TranslateFunction, routes: Record<string, TranslateFunction>): TranslateFunction;
+/** The fields of a Level the display helpers read. */
+export interface LevelDisplaySource {
+    level: number;
+    title?: string | null;
+    text?: string | null;
+    localization?: {
+        title?: LocalizedHint;
+        text?: LocalizedHint;
+    };
+}
+/** The fields of a Technique the display helpers read. */
+export interface TechniqueDisplaySource {
+    title?: string | null;
+    path?: string | null;
+    localization?: {
+        title?: LocalizedHint;
+        text?: LocalizedHint;
+    };
+}
+/**
+ * Display title for a level, the way both apps build it:
+ * `localizedField(tEntity, level.localization?.title, '')`, then
+ * `tLevels(`${level}.title`, level.title)`, then the raw title.
+ *
+ * @param tEntity - Entity translate function (see createNamespacedTranslate)
+ * @param tLevels - Optional translate function for the `levels` namespace
+ * @returns '' when nothing is available (apps may then show "Level N")
+ */
+export declare function getLevelDisplayTitle(level: LevelDisplaySource, tEntity: TranslateFunction, tLevels?: TranslateFunction): string;
+/**
+ * Display description for a level: `localization.text`, then
+ * `tLevels(`${level}.text`, level.text)`, then the raw text ('' if none).
+ */
+export declare function getLevelDisplayText(level: LevelDisplaySource, tEntity: TranslateFunction, tLevels?: TranslateFunction): string;
+/**
+ * Display title for a technique: `localization.title`, then
+ * `tTechniques(`${canonicalPath}.title`, technique.title)`, then the raw title.
+ *
+ * The namespace key uses the canonical path (`3d-medusa` → `medusa-coloring`),
+ * which is how `techniques.json` is keyed.
+ *
+ * @param tEntity - Entity translate function (see createNamespacedTranslate)
+ * @param tTechniques - Optional translate function for the `techniques` namespace
+ */
+export declare function getTechniqueDisplayTitle(technique: TechniqueDisplaySource, tEntity: TranslateFunction, tTechniques?: TranslateFunction): string;
+/**
+ * Display name of the belt for a level (e.g. "Yellow"), as AchievementModal
+ * shows it: `tBelts(`${level}.name`, belt.name)` in the `belts` namespace,
+ * falling back to the belt's English name ('' for an unknown level).
+ *
+ * @param tBelts - Optional translate function for the `belts` namespace
+ */
+export declare function getBeltDisplayName(level: number, tBelts?: TranslateFunction): string;
+/**
+ * Display label of the belt for a level (e.g. "Yellow Belt"):
+ * `tBelts(`${level}.label`, `${belt.name} Belt`)` in the `belts` namespace,
+ * falling back to `"<name> Belt"` ('' for an unknown level).
+ *
+ * @param tBelts - Optional translate function for the `belts` namespace
+ */
+export declare function getBeltDisplayLabel(level: number, tBelts?: TranslateFunction): string;
+/**
+ * The fields of a Strategy the display helper reads. The API's Strategy has
+ * only `stub` today; `title` / `localization` are read when present.
+ */
+export interface StrategyDisplaySource {
+    stub: string;
+    title?: string | null;
+    localization?: {
+        title?: LocalizedHint;
+    };
+}
+/**
+ * Display title for a strategy: `localization.title`, then
+ * `tStrategies(`${stub}.title`, title ?? stub)`, then the raw title, then the
+ * stub (the apps' `tStrat(`${stub}.title`, stub)`).
+ *
+ * @param tEntity - Entity translate function (see createNamespacedTranslate)
+ * @param tStrategies - Optional translate function for the `strategies` namespace
+ */
+export declare function getStrategyDisplayTitle(strategy: StrategyDisplaySource, tEntity: TranslateFunction, tStrategies?: TranslateFunction): string;
+//# sourceMappingURL=entityTranslate.d.ts.map

package/dist/utils/entityTranslate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityTranslate.d.ts","sourceRoot":"","sources":["../../src/utils/entityTranslate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACxC,iBAAiB,CAenB;AAeD,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,aAAa,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC;CAChE;AAED,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,aAAa,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC;CAChE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,MAAM,CAOR;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,iBAAiB,GAC9B,MAAM,CAUR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAIR;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,iBAAiB,GAC9B,MAAM,CASR"}

package/dist/utils/entityTranslate.js

@@ -0,0 +1,146 @@
+/**
+ * Translation of API entities (levels, techniques, badges) in the apps.
+ *
+ * Two key schemes are in use, and this file documents both:
+ *
+ * 1. **API localization keys** (`level.localization.title.stringKey`): dotted
+ *    paths whose first segment names the entity family, e.g. `levels.3.title`,
+ *    `techniques.full-house.title`, `badges.level_1.title`. Resolve them with
+ *    `localizedField(tEntity, ...)` where `tEntity` comes from
+ *    {@link createNamespacedTranslate}.
+ * 2. **Namespace keys** the apps look up directly in an i18next namespace:
+ *    `${level}.title` / `${level}.text` in `levels`, `${path}.title` in
+ *    `techniques`, `${level}.name` / `${level}.label` in `belts`.
+ *
+ * The older helpers in `i18nKeys.ts` (`getLevelKey` → `levels.N`,
+ * `getBeltKey` → `belts.N.name`) build keys for a single merged namespace and
+ * keep that behavior; the display helpers here match what the apps render.
+ */
+import { getBeltForLevel } from '@sudobility/sudojo_types';
+import { localizedField } from './localizedHint';
+import { toCanonicalTechniquePath } from './technique';
+/**
+ * Route entity keys to the i18next namespace that holds them.
+ *
+ * Some families live in their own namespace whose file is NOT nested under the
+ * family segment (`levels.json` is `{ "3": { "title": ... } }`), so a key like
+ * `levels.3.title` only resolves once the prefix is stripped and the lookup is
+ * routed to that namespace. Others (`badges.*`) live nested inside the default
+ * namespace and resolve as-is.
+ *
+ * On a miss the returned function defers to `fallback` with the untouched key,
+ * so callers such as `localizedField` still get the original key back, detect
+ * the miss, and fall back to the raw API value.
+ *
+ * @example
+ * const tEntity = createNamespacedTranslate(tApp, { levels: tLevels, techniques: tTechniques });
+ * localizedField(tEntity, level.localization?.title, level.title);
+ */
+export function createNamespacedTranslate(fallback, routes) {
+    return (key, values) => {
+        for (const [prefix, translate] of Object.entries(routes)) {
+            const scope = `${prefix}.`;
+            if (!key.startsWith(scope))
+                continue;
+            const scopedKey = key.slice(scope.length);
+            const translated = translate(scopedKey, values);
+            // i18next returns the key itself when the translation is missing.
+            if (translated !== scopedKey)
+                return translated;
+            break;
+        }
+        return fallback(key, values);
+    };
+}
+/**
+ * Translate `key` with i18next-style `defaultValue`, treating a result equal to
+ * the key (a `t` that ignores defaultValue) or '' as a miss.
+ */
+function translateOr(t, key, fallback) {
+    const translated = t(key, { defaultValue: fallback });
+    return translated && translated !== key ? translated : fallback;
+}
+/**
+ * Display title for a level, the way both apps build it:
+ * `localizedField(tEntity, level.localization?.title, '')`, then
+ * `tLevels(`${level}.title`, level.title)`, then the raw title.
+ *
+ * @param tEntity - Entity translate function (see createNamespacedTranslate)
+ * @param tLevels - Optional translate function for the `levels` namespace
+ * @returns '' when nothing is available (apps may then show "Level N")
+ */
+export function getLevelDisplayTitle(level, tEntity, tLevels) {
+    const raw = level.title ?? '';
+    return (localizedField(tEntity, level.localization?.title, '') ||
+        (tLevels ? translateOr(tLevels, `${level.level}.title`, raw) : '') ||
+        raw);
+}
+/**
+ * Display description for a level: `localization.text`, then
+ * `tLevels(`${level}.text`, level.text)`, then the raw text ('' if none).
+ */
+export function getLevelDisplayText(level, tEntity, tLevels) {
+    const raw = level.text ?? '';
+    return (localizedField(tEntity, level.localization?.text, '') ||
+        (tLevels ? translateOr(tLevels, `${level.level}.text`, raw) : '') ||
+        raw);
+}
+/**
+ * Display title for a technique: `localization.title`, then
+ * `tTechniques(`${canonicalPath}.title`, technique.title)`, then the raw title.
+ *
+ * The namespace key uses the canonical path (`3d-medusa` → `medusa-coloring`),
+ * which is how `techniques.json` is keyed.
+ *
+ * @param tEntity - Entity translate function (see createNamespacedTranslate)
+ * @param tTechniques - Optional translate function for the `techniques` namespace
+ */
+export function getTechniqueDisplayTitle(technique, tEntity, tTechniques) {
+    const raw = technique.title ?? '';
+    const path = toCanonicalTechniquePath(technique.path);
+    return (localizedField(tEntity, technique.localization?.title, '') ||
+        (tTechniques && path
+            ? translateOr(tTechniques, `${path}.title`, raw)
+            : '') ||
+        raw);
+}
+/**
+ * Display name of the belt for a level (e.g. "Yellow"), as AchievementModal
+ * shows it: `tBelts(`${level}.name`, belt.name)` in the `belts` namespace,
+ * falling back to the belt's English name ('' for an unknown level).
+ *
+ * @param tBelts - Optional translate function for the `belts` namespace
+ */
+export function getBeltDisplayName(level, tBelts) {
+    const raw = getBeltForLevel(level)?.name ?? '';
+    return tBelts ? translateOr(tBelts, `${level}.name`, raw) : raw;
+}
+/**
+ * Display label of the belt for a level (e.g. "Yellow Belt"):
+ * `tBelts(`${level}.label`, `${belt.name} Belt`)` in the `belts` namespace,
+ * falling back to `"<name> Belt"` ('' for an unknown level).
+ *
+ * @param tBelts - Optional translate function for the `belts` namespace
+ */
+export function getBeltDisplayLabel(level, tBelts) {
+    const name = getBeltForLevel(level)?.name;
+    const raw = name ? `${name} Belt` : '';
+    return tBelts ? translateOr(tBelts, `${level}.label`, raw) : raw;
+}
+/**
+ * Display title for a strategy: `localization.title`, then
+ * `tStrategies(`${stub}.title`, title ?? stub)`, then the raw title, then the
+ * stub (the apps' `tStrat(`${stub}.title`, stub)`).
+ *
+ * @param tEntity - Entity translate function (see createNamespacedTranslate)
+ * @param tStrategies - Optional translate function for the `strategies` namespace
+ */
+export function getStrategyDisplayTitle(strategy, tEntity, tStrategies) {
+    const raw = strategy.title || strategy.stub;
+    return (localizedField(tEntity, strategy.localization?.title, '') ||
+        (tStrategies
+            ? translateOr(tStrategies, `${strategy.stub}.title`, raw)
+            : '') ||
+        raw);
+}
+//# sourceMappingURL=entityTranslate.js.map

package/dist/utils/entityTranslate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityTranslate.js","sourceRoot":"","sources":["../../src/utils/entityTranslate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Translation of API entities (levels, techniques, badges) in the apps.\n *\n * Two key schemes are in use, and this file documents both:\n *\n * 1. **API localization keys** (`level.localization.title.stringKey`): dotted\n *    paths whose first segment names the entity family, e.g. `levels.3.title`,\n *    `techniques.full-house.title`, `badges.level_1.title`. Resolve them with\n *    `localizedField(tEntity, ...)` where `tEntity` comes from\n *    {@link createNamespacedTranslate}.\n * 2. **Namespace keys** the apps look up directly in an i18next namespace:\n *    `${level}.title` / `${level}.text` in `levels`, `${path}.title` in\n *    `techniques`, `${level}.name` / `${level}.label` in `belts`.\n *\n * The older helpers in `i18nKeys.ts` (`getLevelKey` → `levels.N`,\n * `getBeltKey` → `belts.N.name`) build keys for a single merged namespace and\n * keep that behavior; the display helpers here match what the apps render.\n */\n\nimport type { LocalizedHint } from '@sudobility/sudojo_types';\nimport { getBeltForLevel } from '@sudobility/sudojo_types';\nimport { localizedField, type TranslateFunction } from './localizedHint';\nimport { toCanonicalTechniquePath } from './technique';\n\n/**\n * Route entity keys to the i18next namespace that holds them.\n *\n * Some families live in their own namespace whose file is NOT nested under the\n * family segment (`levels.json` is `{ \"3\": { \"title\": ... } }`), so a key like\n * `levels.3.title` only resolves once the prefix is stripped and the lookup is\n * routed to that namespace. Others (`badges.*`) live nested inside the default\n * namespace and resolve as-is.\n *\n * On a miss the returned function defers to `fallback` with the untouched key,\n * so callers such as `localizedField` still get the original key back, detect\n * the miss, and fall back to the raw API value.\n *\n * @example\n * const tEntity = createNamespacedTranslate(tApp, { levels: tLevels, techniques: tTechniques });\n * localizedField(tEntity, level.localization?.title, level.title);\n */\nexport function createNamespacedTranslate(\n  fallback: TranslateFunction,\n  routes: Record<string, TranslateFunction>\n): TranslateFunction {\n  return (key, values) => {\n    for (const [prefix, translate] of Object.entries(routes)) {\n      const scope = `${prefix}.`;\n      if (!key.startsWith(scope)) continue;\n\n      const scopedKey = key.slice(scope.length);\n      const translated = translate(scopedKey, values);\n      // i18next returns the key itself when the translation is missing.\n      if (translated !== scopedKey) return translated;\n      break;\n    }\n\n    return fallback(key, values);\n  };\n}\n\n/**\n * Translate `key` with i18next-style `defaultValue`, treating a result equal to\n * the key (a `t` that ignores defaultValue) or '' as a miss.\n */\nfunction translateOr(\n  t: TranslateFunction,\n  key: string,\n  fallback: string\n): string {\n  const translated = t(key, { defaultValue: fallback });\n  return translated && translated !== key ? translated : fallback;\n}\n\n/** The fields of a Level the display helpers read. */\nexport interface LevelDisplaySource {\n  level: number;\n  title?: string | null;\n  text?: string | null;\n  localization?: { title?: LocalizedHint; text?: LocalizedHint };\n}\n\n/** The fields of a Technique the display helpers read. */\nexport interface TechniqueDisplaySource {\n  title?: string | null;\n  path?: string | null;\n  localization?: { title?: LocalizedHint; text?: LocalizedHint };\n}\n\n/**\n * Display title for a level, the way both apps build it:\n * `localizedField(tEntity, level.localization?.title, '')`, then\n * `tLevels(`${level}.title`, level.title)`, then the raw title.\n *\n * @param tEntity - Entity translate function (see createNamespacedTranslate)\n * @param tLevels - Optional translate function for the `levels` namespace\n * @returns '' when nothing is available (apps may then show \"Level N\")\n */\nexport function getLevelDisplayTitle(\n  level: LevelDisplaySource,\n  tEntity: TranslateFunction,\n  tLevels?: TranslateFunction\n): string {\n  const raw = level.title ?? '';\n  return (\n    localizedField(tEntity, level.localization?.title, '') ||\n    (tLevels ? translateOr(tLevels, `${level.level}.title`, raw) : '') ||\n    raw\n  );\n}\n\n/**\n * Display description for a level: `localization.text`, then\n * `tLevels(`${level}.text`, level.text)`, then the raw text ('' if none).\n */\nexport function getLevelDisplayText(\n  level: LevelDisplaySource,\n  tEntity: TranslateFunction,\n  tLevels?: TranslateFunction\n): string {\n  const raw = level.text ?? '';\n  return (\n    localizedField(tEntity, level.localization?.text, '') ||\n    (tLevels ? translateOr(tLevels, `${level.level}.text`, raw) : '') ||\n    raw\n  );\n}\n\n/**\n * Display title for a technique: `localization.title`, then\n * `tTechniques(`${canonicalPath}.title`, technique.title)`, then the raw title.\n *\n * The namespace key uses the canonical path (`3d-medusa` → `medusa-coloring`),\n * which is how `techniques.json` is keyed.\n *\n * @param tEntity - Entity translate function (see createNamespacedTranslate)\n * @param tTechniques - Optional translate function for the `techniques` namespace\n */\nexport function getTechniqueDisplayTitle(\n  technique: TechniqueDisplaySource,\n  tEntity: TranslateFunction,\n  tTechniques?: TranslateFunction\n): string {\n  const raw = technique.title ?? '';\n  const path = toCanonicalTechniquePath(technique.path);\n  return (\n    localizedField(tEntity, technique.localization?.title, '') ||\n    (tTechniques && path\n      ? translateOr(tTechniques, `${path}.title`, raw)\n      : '') ||\n    raw\n  );\n}\n\n/**\n * Display name of the belt for a level (e.g. \"Yellow\"), as AchievementModal\n * shows it: `tBelts(`${level}.name`, belt.name)` in the `belts` namespace,\n * falling back to the belt's English name ('' for an unknown level).\n *\n * @param tBelts - Optional translate function for the `belts` namespace\n */\nexport function getBeltDisplayName(\n  level: number,\n  tBelts?: TranslateFunction\n): string {\n  const raw = getBeltForLevel(level)?.name ?? '';\n  return tBelts ? translateOr(tBelts, `${level}.name`, raw) : raw;\n}\n\n/**\n * Display label of the belt for a level (e.g. \"Yellow Belt\"):\n * `tBelts(`${level}.label`, `${belt.name} Belt`)` in the `belts` namespace,\n * falling back to `\"<name> Belt\"` ('' for an unknown level).\n *\n * @param tBelts - Optional translate function for the `belts` namespace\n */\nexport function getBeltDisplayLabel(\n  level: number,\n  tBelts?: TranslateFunction\n): string {\n  const name = getBeltForLevel(level)?.name;\n  const raw = name ? `${name} Belt` : '';\n  return tBelts ? translateOr(tBelts, `${level}.label`, raw) : raw;\n}\n\n/**\n * The fields of a Strategy the display helper reads. The API's Strategy has\n * only `stub` today; `title` / `localization` are read when present.\n */\nexport interface StrategyDisplaySource {\n  stub: string;\n  title?: string | null;\n  localization?: { title?: LocalizedHint };\n}\n\n/**\n * Display title for a strategy: `localization.title`, then\n * `tStrategies(`${stub}.title`, title ?? stub)`, then the raw title, then the\n * stub (the apps' `tStrat(`${stub}.title`, stub)`).\n *\n * @param tEntity - Entity translate function (see createNamespacedTranslate)\n * @param tStrategies - Optional translate function for the `strategies` namespace\n */\nexport function getStrategyDisplayTitle(\n  strategy: StrategyDisplaySource,\n  tEntity: TranslateFunction,\n  tStrategies?: TranslateFunction\n): string {\n  const raw = strategy.title || strategy.stub;\n  return (\n    localizedField(tEntity, strategy.localization?.title, '') ||\n    (tStrategies\n      ? translateOr(tStrategies, `${strategy.stub}.title`, raw)\n      : '') ||\n    raw\n  );\n}\n"]}

package/dist/utils/gameFetchStatus.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Status of a game fetch (useLevelGame / useDailyGame): which screen to show.
+ */
+/** Game fetch status indicating what screen to show */
+export type GameFetchStatus = 'loading' | 'success' | 'auth_required' | 'subscription_required' | 'entitlement_required' | 'error';
+/**
+ * API response with the optional `action` field older Sudojo API deployments
+ * attached to gated responses.
+ */
+export interface GameFetchResponse {
+    success: boolean;
+    data?: unknown;
+    action?: {
+        type: string;
+        options?: string[];
+    };
+}
+/**
+ * Whether a response or error says the user must sign in.
+ *
+ * Legacy: the current sudojo_api never sends `action: { type: 'auth_required' }`
+ * or an "Account required" message (its puzzle and daily GETs are public), so
+ * this is false against it. Kept for older deployments; not provably
+ * unreachable, because `error` can be anything the network layer throws.
+ */
+export declare function isAuthRequiredResponse(response: GameFetchResponse | null | undefined, error: unknown): boolean;
+/**
+ * Whether a response or error says a subscription is required.
+ *
+ * Legacy: the current sudojo_api never sends
+ * `action: { type: 'subscription_required' }` or "Daily limit reached" (its
+ * daily-limit gate was deleted). The `'subscription'` substring check still
+ * matches any error message containing that word, so it is kept.
+ */
+export declare function isSubscriptionRequiredResponse(response: GameFetchResponse | null | undefined, error: unknown): boolean;
+/**
+ * Derive the fetch status for a game query, in priority order:
+ * entitlement denied, loading, auth required, subscription required, error,
+ * success (a successful response with data), otherwise still loading.
+ */
+export declare function getGameFetchStatus(state: {
+    isLoading: boolean;
+    response: GameFetchResponse | null | undefined;
+    error: unknown;
+    entitlementDenied?: boolean;
+}): GameFetchStatus;
+/**
+ * HTTP status carried by an error, when it has one. The apps' network
+ * clients throw a NetworkError (`@sudobility/types`) with a numeric `status`
+ * for non-2xx responses.
+ */
+export declare function getErrorHttpStatus(error: unknown): number | undefined;
+/** Status of a practice fetch (usePracticeGame): which screen to show. */
+export type PracticeFetchStatus = 'loading' | 'ready' | 'auth_required' | 'subscription_required' | 'no_practices' | 'error';
+/**
+ * Derive the practice fetch status (web PracticePage / RN PracticeScreen):
+ * - error: HTTP 401 -> auth_required, 402 -> subscription_required, any other
+ *   status -> error; an error without a status falls back to its message
+ *   ('401'/'auth' -> auth_required, '402'/'subscription' ->
+ *   subscription_required)
+ * - `success: false` with "No practices found" -> no_practices, else error
+ * - a practice -> ready; a successful response without one -> no_practices
+ * - otherwise loading
+ */
+export declare function getPracticeFetchStatus(state: {
+    isLoading: boolean;
+    response: {
+        success: boolean;
+        data?: unknown;
+        error?: string | null | undefined;
+    } | null | undefined;
+    error: unknown;
+}): PracticeFetchStatus;
+//# sourceMappingURL=gameFetchStatus.d.ts.map

package/dist/utils/gameFetchStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gameFetchStatus.d.ts","sourceRoot":"","sources":["../../src/utils/gameFetchStatus.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,uDAAuD;AACvD,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,SAAS,GACT,eAAe,GACf,uBAAuB,GACvB,sBAAsB,GACtB,OAAO,CAAC;AAEZ;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AASD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC9C,KAAK,EAAE,OAAO,GACb,OAAO,CAQT;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC9C,KAAK,EAAE,OAAO,GACb,OAAO,CAaT;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,eAAe,CAWlB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMrE;AAED,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,OAAO,GACP,eAAe,GACf,uBAAuB,GACvB,cAAc,GACd,OAAO,CAAC;AAEZ;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EACJ;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;KAAE,GACvE,IAAI,GACJ,SAAS,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,mBAAmB,CAyBtB"}

package/dist/utils/gameFetchStatus.js

@@ -0,0 +1,118 @@
+/**
+ * Status of a game fetch (useLevelGame / useDailyGame): which screen to show.
+ */
+function errorMessage(error) {
+    if (error && typeof error === 'object') {
+        return error.message;
+    }
+    return undefined;
+}
+/**
+ * Whether a response or error says the user must sign in.
+ *
+ * Legacy: the current sudojo_api never sends `action: { type: 'auth_required' }`
+ * or an "Account required" message (its puzzle and daily GETs are public), so
+ * this is false against it. Kept for older deployments; not provably
+ * unreachable, because `error` can be anything the network layer throws.
+ */
+export function isAuthRequiredResponse(response, error) {
+    if (response?.success === false &&
+        response.action?.type === 'auth_required') {
+        return true;
+    }
+    return errorMessage(error)?.includes('Account required') ?? false;
+}
+/**
+ * Whether a response or error says a subscription is required.
+ *
+ * Legacy: the current sudojo_api never sends
+ * `action: { type: 'subscription_required' }` or "Daily limit reached" (its
+ * daily-limit gate was deleted). The `'subscription'` substring check still
+ * matches any error message containing that word, so it is kept.
+ */
+export function isSubscriptionRequiredResponse(response, error) {
+    if (response?.success === false &&
+        response.action?.type === 'subscription_required') {
+        return true;
+    }
+    const message = errorMessage(error);
+    return ((message?.includes('Daily limit reached') ||
+        message?.includes('subscription')) ??
+        false);
+}
+/**
+ * Derive the fetch status for a game query, in priority order:
+ * entitlement denied, loading, auth required, subscription required, error,
+ * success (a successful response with data), otherwise still loading.
+ */
+export function getGameFetchStatus(state) {
+    const { isLoading, response, error, entitlementDenied = false } = state;
+    if (entitlementDenied)
+        return 'entitlement_required';
+    if (isLoading)
+        return 'loading';
+    if (isAuthRequiredResponse(response, error))
+        return 'auth_required';
+    if (isSubscriptionRequiredResponse(response, error)) {
+        return 'subscription_required';
+    }
+    if (error)
+        return 'error';
+    if (response?.success && response.data)
+        return 'success';
+    return 'loading';
+}
+/**
+ * HTTP status carried by an error, when it has one. The apps' network
+ * clients throw a NetworkError (`@sudobility/types`) with a numeric `status`
+ * for non-2xx responses.
+ */
+export function getErrorHttpStatus(error) {
+    if (error && typeof error === 'object') {
+        const status = error.status;
+        if (typeof status === 'number')
+            return status;
+    }
+    return undefined;
+}
+/**
+ * Derive the practice fetch status (web PracticePage / RN PracticeScreen):
+ * - error: HTTP 401 -> auth_required, 402 -> subscription_required, any other
+ *   status -> error; an error without a status falls back to its message
+ *   ('401'/'auth' -> auth_required, '402'/'subscription' ->
+ *   subscription_required)
+ * - `success: false` with "No practices found" -> no_practices, else error
+ * - a practice -> ready; a successful response without one -> no_practices
+ * - otherwise loading
+ */
+export function getPracticeFetchStatus(state) {
+    const { isLoading, response, error } = state;
+    if (isLoading)
+        return 'loading';
+    if (error) {
+        const httpStatus = getErrorHttpStatus(error);
+        if (httpStatus === 401)
+            return 'auth_required';
+        if (httpStatus === 402)
+            return 'subscription_required';
+        if (httpStatus === undefined) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('401') || message.includes('auth')) {
+                return 'auth_required';
+            }
+            if (message.includes('402') || message.includes('subscription')) {
+                return 'subscription_required';
+            }
+        }
+        return 'error';
+    }
+    if (response?.success === false) {
+        return response.error?.includes('No practices found')
+            ? 'no_practices'
+            : 'error';
+    }
+    if (response?.success)
+        return response.data ? 'ready' : 'no_practices';
+    return 'loading';
+}
+//# sourceMappingURL=gameFetchStatus.js.map

package/dist/utils/gameFetchStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gameFetchStatus.js","sourceRoot":"","sources":["../../src/utils/gameFetchStatus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Status of a game fetch (useLevelGame / useDailyGame): which screen to show.\n */\n\n/** Game fetch status indicating what screen to show */\nexport type GameFetchStatus =\n  | 'loading'\n  | 'success'\n  | 'auth_required'\n  | 'subscription_required'\n  | 'entitlement_required'\n  | 'error';\n\n/**\n * API response with the optional `action` field older Sudojo API deployments\n * attached to gated responses.\n */\nexport interface GameFetchResponse {\n  success: boolean;\n  data?: unknown;\n  action?: {\n    type: string;\n    options?: string[];\n  };\n}\n\nfunction errorMessage(error: unknown): string | undefined {\n  if (error && typeof error === 'object') {\n    return (error as { message?: string }).message;\n  }\n  return undefined;\n}\n\n/**\n * Whether a response or error says the user must sign in.\n *\n * Legacy: the current sudojo_api never sends `action: { type: 'auth_required' }`\n * or an \"Account required\" message (its puzzle and daily GETs are public), so\n * this is false against it. Kept for older deployments; not provably\n * unreachable, because `error` can be anything the network layer throws.\n */\nexport function isAuthRequiredResponse(\n  response: GameFetchResponse | null | undefined,\n  error: unknown\n): boolean {\n  if (\n    response?.success === false &&\n    response.action?.type === 'auth_required'\n  ) {\n    return true;\n  }\n  return errorMessage(error)?.includes('Account required') ?? false;\n}\n\n/**\n * Whether a response or error says a subscription is required.\n *\n * Legacy: the current sudojo_api never sends\n * `action: { type: 'subscription_required' }` or \"Daily limit reached\" (its\n * daily-limit gate was deleted). The `'subscription'` substring check still\n * matches any error message containing that word, so it is kept.\n */\nexport function isSubscriptionRequiredResponse(\n  response: GameFetchResponse | null | undefined,\n  error: unknown\n): boolean {\n  if (\n    response?.success === false &&\n    response.action?.type === 'subscription_required'\n  ) {\n    return true;\n  }\n  const message = errorMessage(error);\n  return (\n    (message?.includes('Daily limit reached') ||\n      message?.includes('subscription')) ??\n    false\n  );\n}\n\n/**\n * Derive the fetch status for a game query, in priority order:\n * entitlement denied, loading, auth required, subscription required, error,\n * success (a successful response with data), otherwise still loading.\n */\nexport function getGameFetchStatus(state: {\n  isLoading: boolean;\n  response: GameFetchResponse | null | undefined;\n  error: unknown;\n  entitlementDenied?: boolean;\n}): GameFetchStatus {\n  const { isLoading, response, error, entitlementDenied = false } = state;\n  if (entitlementDenied) return 'entitlement_required';\n  if (isLoading) return 'loading';\n  if (isAuthRequiredResponse(response, error)) return 'auth_required';\n  if (isSubscriptionRequiredResponse(response, error)) {\n    return 'subscription_required';\n  }\n  if (error) return 'error';\n  if (response?.success && response.data) return 'success';\n  return 'loading';\n}\n\n/**\n * HTTP status carried by an error, when it has one. The apps' network\n * clients throw a NetworkError (`@sudobility/types`) with a numeric `status`\n * for non-2xx responses.\n */\nexport function getErrorHttpStatus(error: unknown): number | undefined {\n  if (error && typeof error === 'object') {\n    const status = (error as { status?: unknown }).status;\n    if (typeof status === 'number') return status;\n  }\n  return undefined;\n}\n\n/** Status of a practice fetch (usePracticeGame): which screen to show. */\nexport type PracticeFetchStatus =\n  | 'loading'\n  | 'ready'\n  | 'auth_required'\n  | 'subscription_required'\n  | 'no_practices'\n  | 'error';\n\n/**\n * Derive the practice fetch status (web PracticePage / RN PracticeScreen):\n * - error: HTTP 401 -> auth_required, 402 -> subscription_required, any other\n *   status -> error; an error without a status falls back to its message\n *   ('401'/'auth' -> auth_required, '402'/'subscription' ->\n *   subscription_required)\n * - `success: false` with \"No practices found\" -> no_practices, else error\n * - a practice -> ready; a successful response without one -> no_practices\n * - otherwise loading\n */\nexport function getPracticeFetchStatus(state: {\n  isLoading: boolean;\n  response:\n    | { success: boolean; data?: unknown; error?: string | null | undefined }\n    | null\n    | undefined;\n  error: unknown;\n}): PracticeFetchStatus {\n  const { isLoading, response, error } = state;\n  if (isLoading) return 'loading';\n  if (error) {\n    const httpStatus = getErrorHttpStatus(error);\n    if (httpStatus === 401) return 'auth_required';\n    if (httpStatus === 402) return 'subscription_required';\n    if (httpStatus === undefined) {\n      const message = error instanceof Error ? error.message : String(error);\n      if (message.includes('401') || message.includes('auth')) {\n        return 'auth_required';\n      }\n      if (message.includes('402') || message.includes('subscription')) {\n        return 'subscription_required';\n      }\n    }\n    return 'error';\n  }\n  if (response?.success === false) {\n    return response.error?.includes('No practices found')\n      ? 'no_practices'\n      : 'error';\n  }\n  if (response?.success) return response.data ? 'ready' : 'no_practices';\n  return 'loading';\n}\n"]}

package/dist/utils/gamification.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Gamification helpers: badge progress for the profile / statistics screens.
+ */
+import type { BadgeDefinition } from '@sudobility/sudojo_types';
+/** `badgeType` of the per-level mastery badges (`level_<n>`). */
+export declare const LEVEL_MASTERY_BADGE_TYPE = "level_mastery";
+/** `badgeType` of the games-played milestone badges (`games_<n>`). */
+export declare const GAMES_PLAYED_BADGE_TYPE = "games_played";
+/** Badge definitions split for display, with earned lookup. */
+export interface BadgeProgress<B extends BadgeDefinitionLike = BadgeDefinition> {
+    /** `level_mastery` badges, by requirementValue (the level) ascending */
+    levelBadges: B[];
+    /** `games_played` badges, by requirementValue (games) ascending */
+    gameBadges: B[];
+    /** Whether the user has earned the badge with this key */
+    isEarned: (badgeKey: string) => boolean;
+    /** Number of earned badges (distinct keys) */
+    earnedCount: number;
+    /** Number of badge definitions */
+    totalCount: number;
+}
+/** The fields of a badge definition groupBadgeProgress reads. */
+export type BadgeDefinitionLike = Pick<BadgeDefinition, 'badgeKey' | 'badgeType' | 'requirementValue'>;
+/**
+ * Split badge definitions into level-mastery and games-played lists, each
+ * sorted by requirementValue, as the web ProfilePage and the RN settings /
+ * statistics screens show them. Other badge types are left out of both lists
+ * but still count in `totalCount`.
+ *
+ * @param definitions - All badge definitions (GET /gamification/badges)
+ * @param earned - The user's earned badges (`stats.badges`)
+ */
+export declare function groupBadgeProgress<B extends BadgeDefinitionLike>(definitions: readonly B[] | null | undefined, earned: ReadonlyArray<{
+    badgeKey: string;
+}> | null | undefined): BadgeProgress<B>;
+//# sourceMappingURL=gamification.d.ts.map

package/dist/utils/gamification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamification.d.ts","sourceRoot":"","sources":["../../src/utils/gamification.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,WAAW,aAAa,CAC5B,CAAC,SAAS,mBAAmB,GAAG,eAAe;IAE/C,wEAAwE;IACxE,WAAW,EAAE,CAAC,EAAE,CAAC;IACjB,mEAAmE;IACnE,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,eAAe,EACf,UAAU,GAAG,WAAW,GAAG,kBAAkB,CAC9C,CAAC;AAKF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,mBAAmB,EAC9D,WAAW,EAAE,SAAS,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,EAC5C,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC7D,aAAa,CAAC,CAAC,CAAC,CAclB"}

package/dist/utils/gamification.js

@@ -0,0 +1,33 @@
+/**
+ * Gamification helpers: badge progress for the profile / statistics screens.
+ */
+/** `badgeType` of the per-level mastery badges (`level_<n>`). */
+export const LEVEL_MASTERY_BADGE_TYPE = 'level_mastery';
+/** `badgeType` of the games-played milestone badges (`games_<n>`). */
+export const GAMES_PLAYED_BADGE_TYPE = 'games_played';
+const byRequirement = (a, b) => (a.requirementValue ?? 0) - (b.requirementValue ?? 0);
+/**
+ * Split badge definitions into level-mastery and games-played lists, each
+ * sorted by requirementValue, as the web ProfilePage and the RN settings /
+ * statistics screens show them. Other badge types are left out of both lists
+ * but still count in `totalCount`.
+ *
+ * @param definitions - All badge definitions (GET /gamification/badges)
+ * @param earned - The user's earned badges (`stats.badges`)
+ */
+export function groupBadgeProgress(definitions, earned) {
+    const all = definitions ?? [];
+    const earnedKeys = new Set((earned ?? []).map(b => b.badgeKey));
+    return {
+        levelBadges: all
+            .filter(b => b.badgeType === LEVEL_MASTERY_BADGE_TYPE)
+            .sort(byRequirement),
+        gameBadges: all
+            .filter(b => b.badgeType === GAMES_PLAYED_BADGE_TYPE)
+            .sort(byRequirement),
+        isEarned: badgeKey => earnedKeys.has(badgeKey),
+        earnedCount: earnedKeys.size,
+        totalCount: all.length,
+    };
+}
+//# sourceMappingURL=gamification.js.map

package/dist/utils/gamification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamification.js","sourceRoot":"","sources":["../../src/utils/gamification.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,cAAc,CAAC;AAwBtD,MAAM,aAAa,GAAG,CAAC,CAAsB,EAAE,CAAsB,EAAE,EAAE,CACvE,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAA4C,EAC5C,MAA8D;IAE9D,MAAM,GAAG,GAAG,WAAW,IAAI,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO;QACL,WAAW,EAAE,GAAG;aACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,wBAAwB,CAAC;aACrD,IAAI,CAAC,aAAa,CAAC;QACtB,UAAU,EAAE,GAAG;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,uBAAuB,CAAC;aACpD,IAAI,CAAC,aAAa,CAAC;QACtB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC9C,WAAW,EAAE,UAAU,CAAC,IAAI;QAC5B,UAAU,EAAE,GAAG,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Gamification helpers: badge progress for the profile / statistics screens.\n */\n\nimport type { BadgeDefinition } from '@sudobility/sudojo_types';\n\n/** `badgeType` of the per-level mastery badges (`level_<n>`). */\nexport const LEVEL_MASTERY_BADGE_TYPE = 'level_mastery';\n\n/** `badgeType` of the games-played milestone badges (`games_<n>`). */\nexport const GAMES_PLAYED_BADGE_TYPE = 'games_played';\n\n/** Badge definitions split for display, with earned lookup. */\nexport interface BadgeProgress<\n  B extends BadgeDefinitionLike = BadgeDefinition,\n> {\n  /** `level_mastery` badges, by requirementValue (the level) ascending */\n  levelBadges: B[];\n  /** `games_played` badges, by requirementValue (games) ascending */\n  gameBadges: B[];\n  /** Whether the user has earned the badge with this key */\n  isEarned: (badgeKey: string) => boolean;\n  /** Number of earned badges (distinct keys) */\n  earnedCount: number;\n  /** Number of badge definitions */\n  totalCount: number;\n}\n\n/** The fields of a badge definition groupBadgeProgress reads. */\nexport type BadgeDefinitionLike = Pick<\n  BadgeDefinition,\n  'badgeKey' | 'badgeType' | 'requirementValue'\n>;\n\nconst byRequirement = (a: BadgeDefinitionLike, b: BadgeDefinitionLike) =>\n  (a.requirementValue ?? 0) - (b.requirementValue ?? 0);\n\n/**\n * Split badge definitions into level-mastery and games-played lists, each\n * sorted by requirementValue, as the web ProfilePage and the RN settings /\n * statistics screens show them. Other badge types are left out of both lists\n * but still count in `totalCount`.\n *\n * @param definitions - All badge definitions (GET /gamification/badges)\n * @param earned - The user's earned badges (`stats.badges`)\n */\nexport function groupBadgeProgress<B extends BadgeDefinitionLike>(\n  definitions: readonly B[] | null | undefined,\n  earned: ReadonlyArray<{ badgeKey: string }> | null | undefined\n): BadgeProgress<B> {\n  const all = definitions ?? [];\n  const earnedKeys = new Set((earned ?? []).map(b => b.badgeKey));\n  return {\n    levelBadges: all\n      .filter(b => b.badgeType === LEVEL_MASTERY_BADGE_TYPE)\n      .sort(byRequirement),\n    gameBadges: all\n      .filter(b => b.badgeType === GAMES_PLAYED_BADGE_TYPE)\n      .sort(byRequirement),\n    isEarned: badgeKey => earnedKeys.has(badgeKey),\n    earnedCount: earnedKeys.size,\n    totalCount: all.length,\n  };\n}\n"]}