libmodulor 0.4.0 → 0.6.0

package/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    ignore:
+      - dependency-name: "inversify"
+        versions: ["7.x"]
+    groups:
+      dev:
+        dependency-type: "development"
+      prod:
+        dependency-type: "production"

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # CHANGELOG
 
+## v0.6.0 (2025-02-28)
+
+**BREAKING**
+
+- Extract common react elements on web and rn, renaming some of the props : check the new props names and the new `validateFormField` to simplify your overrides
+- Remove `helper` from the exports map : it makes no sense to expose it as it is an executable (see `npx libmodulor` below)
+
+**Added**
+
+- Introduce the `npx libmodulor CreateProject` command
+- Introduce `select` to target `react-web-pure` : it now renders an HTML `select` when the UC input field `hasOptions()`
+
+**Misc**
+
+- Bump `react` to `19.0.0`
+- Add a new "Style the web Target" tutorial step showing how to use `tailwindcss` and `daisyUI` to provide custom components
+
+## v0.5.0 (2025-02-24)
+
+**BREAKING**
+
+- Replace `.js` by `.ts` for `ProductManifest`
+
+**Added**
+
+- Introduce a 3<sup>rd</sup> implementation of `LLMManager` (`OllamaLLMManager`) to run models locally
+- Introduce `LLMManager` with 2 implementations (`MistralAILLMManager` and `OpenAILLMManager`)
+
+**Misc**
+
+- Simplify the signature of `UCDef.ext.http.transform` removing the generic `T` return
+- Add JSDocs and comments for a better in-place documentation (i.e. in .d.ts files)
+- Add the Tutorial code in the repo at `examples/libmodulor-tuto` and add a new "Expose a rn Target" step
+
 ## v0.4.0 (2025-01-31)
 
 **feat(target): introduce react-native-pure**
@@ -15,7 +49,7 @@ To help with the creation of specific targets, we've added a new one : `react-na
 
 **feat(uc): introduce alternate mounting point**
 
-Added a new property `UcDef.ext.http.mountAlsoAt` to be able to define path aliases. See the comment below to understand why.
+Added a new property `UCDef.ext.http.mountAlsoAt` to be able to define path aliases. See the comment below to understand why.
 
 ```typescript
 /**

package/README.md

@@ -27,11 +27,17 @@ Applications created with `libmodulor` have **6 main properties** :
 
 ## 🚀 Getting Started
 
-To get started, we recommend reading the [📖 Introduction](https://github.com/c100k/libmodulor/blob/v0.4.0/docs/Introduction.md) first. It will give you an overview of what `libmodulor` is and how it works.
+If you're discovering `libmodulor`, we recommend reading the [📖 Introduction](https://github.com/c100k/libmodulor/blob/v0.6.0/docs/Introduction.md) first. It will give you an overview of what `libmodulor` is and how it works.
 
-Then, you can follow the [🚀 Tutorial](https://github.com/c100k/libmodulor/blob/v0.4.0/docs/Tutorial.md) that will show you all the main notions by building something real.
+If you want to learn by doing, you can follow the [🚀 Tutorial](https://github.com/c100k/libmodulor/blob/v0.6.0/docs/Tutorial.md). It contains multiple steps showing you the basics of `libmodulor`. We'll build a small Trading app that will allow us to buy an asset from `curl`, a SPA, a CLI, Claude Desktop, an Android mobile app and an iOS mobile app !
 
-Finally, for more advanced usages, go to the [📜 Guides](https://github.com/c100k/libmodulor/blob/v0.4.0/docs/Guides.md).
+If you're felling adventurous, create a project and start building your own application, with your own apps, use cases, products, targets :
+
+```sh
+npx libmodulor CreateProject --outPath ~/Downloads --projectName libmodulor-projx
+```
+
+Finally, for more advanced uses, check out the [📜 Guides](https://github.com/c100k/libmodulor/blob/v0.6.0/docs/Guides.md).
 
 ## 👨‍💻 Contribute
 
@@ -39,4 +45,4 @@ If you think you can help in any way, feel free to contact me (cf. `author` in `
 
 ## ⚖️ License
 
-[LGPL-3.0](./LICENSE)
+[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.6.0/LICENSE)

package/dist/esm/app/workers/AppSrcFilePathBuilder.d.ts

@@ -3,10 +3,26 @@ import type { FSManager, Logger, Worker } from '../../std/index.js';
 import type { AppName } from '../manifest.js';
 export interface Input {
     appName: AppName;
+    /**
+     * If set, it uses this value to build the path. Otherwise, it fallbacks on {@link appsRootPath}.
+     * @see {@link APPS_ROOT_ALIAS}
+     */
     appsRootAlias?: FilePath | undefined;
+    /**
+     * If `true`, it uses {@link APPS_ROOT_ALIAS} to build the path. Otherwise, it checks {@link appsRootAlias}.
+     */
     appsRootAliasUseDefault?: boolean | undefined;
+    /**
+     * @defaultValue {@link APPS_ROOT_DIR_NAME}
+     */
     appsRootPath?: FilePath | undefined;
     ext?: 'js' | 'ts' | undefined;
+    /**
+     * For example, it can be `[APP_MANIFEST_NAME]`.
+     *
+     * Do not include the extension. This must be passed by the caller via {@link ext}.
+     * Indeed, depending on the context, the extension is not needed (e.g. in tests).
+     */
     filePathParts: FilePath[];
 }
 type Output = FilePath;

package/dist/esm/app/workers/AppSrcFilePathBuilder.js

@@ -23,16 +23,18 @@ let AppSrcFilePathBuilder = class AppSrcFilePathBuilder {
         const appPath = this.fsManager.path(appsRootPath ?? APPS_ROOT_DIR_NAME, appName);
         let importPath = '';
         if (appsRootAliasUseDefault) {
-            importPath = this.fsManager.path(APPS_ROOT_ALIAS, appName);
+            importPath = this.fsManager.path(APPS_ROOT_ALIAS, appName); // @apps/MyApp
         }
         else if (appsRootAlias) {
-            importPath = this.fsManager.path(appsRootAlias, appName);
+            importPath = this.fsManager.path(appsRootAlias, appName); // @myapps/MyApp
         }
         else {
-            importPath = this.fsManager.path(appPath);
-            importPath = `./${importPath}`;
+            importPath = this.fsManager.path(appPath); // src/apps/MyApp
+            importPath = `./${importPath}`; // ./src/apps/MyApp
         }
         const filePath = this.fsManager.path(APP_SRC_DIR_NAME, ...filePathParts);
+        // NOTE 1 : We don't check if the path exists because it wouldn't work when using an alias. So we let the caller do it. For example when using `import` it will fail by itself.
+        // NOTE 2 : Not using `path()` to join in order to avoid the initial `./` to be removed (this is the default behavior of node's join function).
         const suffix = ext ? `.${ext}` : '';
         const path = `${importPath}/${filePath}${suffix}`;
         this.logger.trace('Resolving app src', { path });

package/dist/esm/apps/Helper/index.js

@@ -1,2 +1,3 @@
+// Expose only what's necessary
 export { I18n } from './src/i18n.js';
 export { Manifest } from './src/manifest.js';

package/dist/esm/apps/Helper/src/i18n.js

@@ -1,6 +1,8 @@
 export const I18n = {
     en: {
         err_unknown_app: 'Unknown app : {{appPath}}',
+        uc_CreateProject_desc: 'Create a project by initializing a git repo, creating basic config files and installing the required dependencies',
+        uc_CreateProject_label: 'Create a project',
         uc_DeleteGeneratedAppsTests_desc: 'Delete the automated test suite generated for each app',
         uc_DeleteGeneratedAppsTests_label: 'Delete generated apps tests',
         uc_GenerateAppsTests_desc: 'Generate an automated test suite for each app',
@@ -9,6 +11,8 @@ export const I18n = {
         uc_TestApp_label: 'Test app',
         ucif_appPath_desc: 'The path of the app',
         ucif_appsPath_desc: 'The path to the directory containing all the apps',
+        ucif_projectName_desc: "Name of the project conforming to the package.json's spec (i.e. a-z, 0-9, -)",
+        ucif_outPath_desc: 'Path to a directory where to create the project. Do not include the project name in it. It is created recursively if missing.',
         ucif_monkeyTestingTimeoutInMs_desc: 'These tests can take longer than the usual default of 5000ms because they try lots of possibilities',
         ucif_depsMapping_desc: 'The mapping of dependencies in case some of them need a specific pattern (e.g. one directory above the default)',
         ucif_serverPortRangeStart_desc: 'The port number to start with when generating the server to test (incremented by 1) for each app',

package/dist/esm/apps/Helper/src/lib/project.d.ts

@@ -0,0 +1,2 @@
+import type { FileName, Slug } from '../../../../dt/index.js';
+export declare function projectFiles(name: Slug): Map<FileName, string>;

package/dist/esm/apps/Helper/src/lib/project.js

@@ -0,0 +1,120 @@
+const GITIGNORE = `coverage
+dist
+node_modules
+src/apps/**/test/reports
+src/apps/**/test/*.test.ts
+src/products/**/rn/.expo
+.env
+`;
+const BIOME_JSON = `{
+    "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+    "files": {
+        "ignore": ["coverage", "dist", "node_modules"],
+        "ignoreUnknown": true
+    },
+    "formatter": {
+        "indentStyle": "space",
+        "indentWidth": 4
+    },
+    "javascript": {
+        "formatter": {
+            "quoteStyle": "single"
+        },
+        "parser": {
+            "unsafeParameterDecoratorsEnabled": true
+        }
+    }
+}
+`;
+const PACKAGE_JSON = (name) => `{
+    "name": "${name}",
+    "version": "0.1.0",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "lint": "biome check --write .",
+        "test": "tsc && vitest run --passWithNoTests"
+    },
+    "dependencies": {
+        "inversify": "^6.2.2",
+        "libmodulor": "^0.5.0",
+        "reflect-metadata": "^0.2.2"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^1.9.4",
+        "@types/node": "^22.13.5",
+        "@vitest/coverage-v8": "^3.0.7",
+        "buffer": "^6.0.3",
+        "cookie-parser": "^1.4.7",
+        "express": "^4.21.2",
+        "express-fileupload": "^1.5.1",
+        "fast-check": "^3.23.2",
+        "helmet": "^8.0.0",
+        "jose": "^6.0.8",
+        "typescript": "^5.7.3",
+        "vite": "^6.2.0",
+        "vitest": "^3.0.7"
+    }
+}
+`;
+const README_MD = (name) => `# ${name}
+
+🚀🚀🚀
+`;
+const TSCONFIG_JSON = `{
+    "compilerOptions": {
+        "allowSyntheticDefaultImports": true,
+        "declaration": true,
+        "lib": ["dom", "esnext"],
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "noEmit": true,
+        "removeComments": true,
+        "skipLibCheck": true,
+        "sourceMap": true,
+        "target": "ESNext",
+
+        "strict": true,
+        "allowUnreachableCode": false,
+        "allowUnusedLabels": false,
+        "exactOptionalPropertyTypes": true,
+        "noFallthroughCasesInSwitch": true,
+        "noPropertyAccessFromIndexSignature": true,
+        "noImplicitOverride": true,
+        "noImplicitReturns": true,
+        "noUncheckedIndexedAccess": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "verbatimModuleSyntax": true,
+
+        "emitDecoratorMetadata": true,
+        "experimentalDecorators": true,
+
+        "jsx": "react"
+    }
+}
+`;
+const VITEST_CONFIG_TS = `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        coverage: {
+            enabled: true,
+            exclude: ['src/apps/**/test', 'src/**/*.test.ts'],
+            include: ['src'],
+            reporter: ['html', 'lcov', 'text'],
+        },
+        reporters: ['verbose'],
+    },
+});
+`;
+export function projectFiles(name) {
+    return new Map([
+        ['.gitignore', GITIGNORE],
+        ['biome.json', BIOME_JSON],
+        ['package.json', PACKAGE_JSON(name)],
+        ['README.md', README_MD(name)],
+        ['tsconfig.json', TSCONFIG_JSON],
+        ['vitest.config.ts', VITEST_CONFIG_TS],
+    ]);
+}

package/dist/esm/apps/Helper/src/manifest.d.ts

@@ -2,6 +2,11 @@ export declare const Manifest: {
     languageCodes: "en"[];
     name: "Helper";
     ucReg: {
+        CreateProject: {
+            action: "Create";
+            icon: string;
+            name: "CreateProject";
+        };
         DeleteGeneratedAppsTests: {
             action: "Delete";
             icon: string;

package/dist/esm/apps/Helper/src/manifest.js

@@ -2,6 +2,11 @@ export const Manifest = {
     languageCodes: ['en'],
     name: 'Helper',
     ucReg: {
+        CreateProject: {
+            action: 'Create',
+            icon: 'plus',
+            name: 'CreateProject',
+        },
         DeleteGeneratedAppsTests: {
             action: 'Delete',
             icon: 'trash-can',

package/dist/esm/apps/Helper/src/ucds/CreateProjectUCD.d.ts

@@ -0,0 +1,15 @@
+import { type DirPath, type Slug } from '../../../../dt/index.js';
+import type { FSManager, Logger, ShellCommandExecutor } from '../../../../std/index.js';
+import { type UCDef, type UCInput, type UCInputFieldValue, type UCMain, type UCMainInput } from '../../../../uc/index.js';
+export interface CreateProjectInput extends UCInput {
+    outPath: UCInputFieldValue<DirPath>;
+    projectName: UCInputFieldValue<Slug>;
+}
+export declare class CreateProjectClientMain implements UCMain<CreateProjectInput> {
+    private fsManager;
+    private logger;
+    private shellCommandExecutor;
+    constructor(fsManager: FSManager, logger: Logger, shellCommandExecutor: ShellCommandExecutor);
+    exec({ uc }: UCMainInput<CreateProjectInput>): Promise<void>;
+}
+export declare const CreateProjectUCD: UCDef<CreateProjectInput>;

package/dist/esm/apps/Helper/src/ucds/CreateProjectUCD.js

@@ -0,0 +1,118 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'inversify';
+import { APPS_ROOT_PATH, PRODUCTS_ROOT_PATH } from '../../../../convention.js';
+import { TDirPath, TSlug, } from '../../../../dt/index.js';
+import { EverybodyUCPolicy, } from '../../../../uc/index.js';
+import { projectFiles } from '../lib/project.js';
+import { Manifest } from '../manifest.js';
+let CreateProjectClientMain = class CreateProjectClientMain {
+    fsManager;
+    logger;
+    shellCommandExecutor;
+    constructor(fsManager, logger, shellCommandExecutor) {
+        this.fsManager = fsManager;
+        this.logger = logger;
+        this.shellCommandExecutor = shellCommandExecutor;
+    }
+    async exec({ uc }) {
+        const outPath = uc.reqVal0('outPath');
+        const projectName = uc.reqVal0('projectName');
+        const cwd = this.fsManager.path(outPath, projectName);
+        this.logger.info('Creating root dir : %s', cwd);
+        await this.fsManager.mkdir(cwd, { recursive: true });
+        this.logger.info('Initializing git repository');
+        await this.shellCommandExecutor.exec({
+            bin: 'git',
+            opts: { args: ['init'], cwd },
+        });
+        this.logger.info('Creating config files');
+        const files = projectFiles(projectName);
+        for await (const [fileName, content] of files) {
+            const path = this.fsManager.path(cwd, fileName);
+            await this.fsManager.touch(path, content);
+        }
+        const dirs = [APPS_ROOT_PATH, PRODUCTS_ROOT_PATH];
+        this.logger.info('Creating apps and products directories');
+        for await (const dirPath of dirs) {
+            const path = this.fsManager.path(cwd, ...dirPath);
+            await this.fsManager.mkdir(path, { recursive: true });
+            await this.fsManager.touch(this.fsManager.path(path, '.gitkeep'), '');
+        }
+        this.logger.info('Installing dependencies');
+        await this.shellCommandExecutor.exec({
+            bin: 'yarn',
+            opts: { args: ['install'], cwd },
+        });
+        this.logger.info('Committing');
+        const cmdArgs = [
+            ['branch', '-M', 'master'],
+            ['add', '.'],
+            ['commit', '-am', '"chore: initial commit"'],
+        ];
+        for await (const args of cmdArgs) {
+            await this.shellCommandExecutor.exec({
+                bin: 'git',
+                opts: { args, cwd },
+            });
+        }
+        const devCmds = ['lint', 'test'];
+        for await (const cmd of devCmds) {
+            this.logger.info('Testing dev command : yarn %s', cmd);
+            await this.shellCommandExecutor.exec({
+                bin: 'yarn',
+                opts: { args: [cmd], cwd },
+            });
+        }
+        this.logger.info('Done ! Project ready ! ✅ 🚀');
+    }
+};
+CreateProjectClientMain = __decorate([
+    injectable(),
+    __param(0, inject('FSManager')),
+    __param(1, inject('Logger')),
+    __param(2, inject('ShellCommandExecutor')),
+    __metadata("design:paramtypes", [Object, Object, Object])
+], CreateProjectClientMain);
+export { CreateProjectClientMain };
+export const CreateProjectUCD = {
+    ext: {
+        cmd: {
+            mountAt: 'CreateProject',
+        },
+    },
+    io: {
+        i: {
+            fields: {
+                outPath: {
+                    cardinality: {
+                        min: 0,
+                    },
+                    type: new TDirPath()
+                        .setDefaultValue('./')
+                        .setExamples([['~', 'Desktop'].join('/')]),
+                },
+                projectName: {
+                    type: new TSlug(),
+                },
+            },
+        },
+    },
+    lifecycle: {
+        client: {
+            main: CreateProjectClientMain,
+            policy: EverybodyUCPolicy,
+        },
+    },
+    metadata: Manifest.ucReg.CreateProject,
+};

package/dist/esm/apps/Helper/src/ucds/GenerateAppsTestsUCD.js

@@ -36,6 +36,7 @@ let GenerateAppsTestsClientMain = class GenerateAppsTestsClientMain {
         const { apps } = await this.appSrcBrowser.exec({
             appsPath,
         });
+        // Keeping it simple without any defensive programming. Be responsible !
         const depsMappingParsed = new Map((depsMapping || []).map((dm) => dm.split(DEP_MAPPING_SEP)));
         let idx = 0;
         for await (const [appPath] of apps) {
@@ -70,7 +71,7 @@ export const GenerateAppsTestsUCD = {
                 ...AppInputFieldsDef,
                 depsMapping: {
                     cardinality: {
-                        max: 20,
+                        max: 20, // A totally arbitrary number
                         min: 0,
                     },
                     type: new TDepMapping().setExamples([
@@ -91,7 +92,7 @@ export const GenerateAppsTestsUCD = {
                     },
                     type: new THostPort()
                         .setDefaultValue(14_000)
-                        .setExamples([14_000]),
+                        .setExamples([14_000]), // "Calvados ❤️"
                 },
             },
         },

package/dist/esm/bundlers/vite/StripUCDLifecycleServerPlugin.js

@@ -1,6 +1,9 @@
 import { UC_DEF_FILE_NAME_SUFFIX } from '../../convention.js';
 import { stripUCDLifecycleServer } from '../../uc/index.js';
 export const StripUCDLifecycleServerPlugin = {
+    // Why enforce ?
+    // Otherwise Rollup parses the file and strips trailing commas.
+    // We need them to strip correctly (although the implementation will be made more robust).
     enforce: 'pre',
     name: 'strip-ucd-lifecycle-server',
     transform: (src, id) => {

package/dist/esm/convention.d.ts

@@ -23,6 +23,7 @@ export declare const APP_TEST_REPORTS_DIR_NAME: string;
 export declare const PRODUCTS_ROOT_ALIAS: string;
 export declare const PRODUCTS_ROOT_PATH: string[];
 export declare const PRODUCT_MANIFEST_NAME: string;
+export declare const PRODUCT_MANIFEST_FILE_EXT: string;
 export declare const PRODUCT_MANIFEST_FILE_NAME: string;
 export declare const PRODUCT_NAME_PLACEHOLDER: ProductName;
 export declare const UC_DEF_SUFFIX: string;

package/dist/esm/convention.js

@@ -1,4 +1,10 @@
+/*
+ * Common
+ */
 export const SRC_DIR_NAME = 'src';
+/*
+ * App
+ */
 export const APPS_ROOT_DIR_NAME = 'apps';
 export const APPS_ROOT_ALIAS = `@${APPS_ROOT_DIR_NAME}`;
 export const APPS_ROOT_PATH = [SRC_DIR_NAME, APPS_ROOT_DIR_NAME];
@@ -7,22 +13,29 @@ export const APP_I18N_NAME = 'I18n';
 export const APP_I18N_FILE_NAME = `${APP_I18N_NAME.toLowerCase()}.ts`;
 export const APP_INDEX_NAME = 'index';
 export const APP_INDEX_FILE_NAME = `${APP_INDEX_NAME}.ts`;
-export const APP_INDEX_FILE_NAME_FOR_IMPORT = 'index.js';
+export const APP_INDEX_FILE_NAME_FOR_IMPORT = 'index.js'; // ESM
 export const APP_MANIFEST_NAME = 'Manifest';
 export const APP_MANIFEST_FILE_EXT = '.ts';
-export const APP_MANIFEST_FILE_NAME = `${APP_MANIFEST_NAME.toLowerCase()}.ts`;
+export const APP_MANIFEST_FILE_NAME = `${APP_MANIFEST_NAME.toLowerCase()}${APP_MANIFEST_FILE_EXT}`;
 export const APP_NAME_PLACEHOLDER = 'AppX';
-export const APP_ROOT_FROM_UCD = ['..', '..', '..'];
+export const APP_ROOT_FROM_UCD = ['..', '..', '..']; // $root/src/ucds/XyzUCD.ts
 export const APP_SRC_DIR_NAME = SRC_DIR_NAME;
 export const APP_SRC_UCDS_DIR_NAME = 'ucds';
 export const APP_TEST_DIR_NAME = 'test';
 export const APP_TEST_MAIN_FILE_NAME = 'App.test.ts';
 export const APP_TEST_REPORTS_DIR_NAME = 'reports';
+/*
+ * Product
+ */
 export const PRODUCTS_ROOT_ALIAS = '@p';
 export const PRODUCTS_ROOT_PATH = [SRC_DIR_NAME, 'products'];
 export const PRODUCT_MANIFEST_NAME = 'Manifest';
-export const PRODUCT_MANIFEST_FILE_NAME = `${PRODUCT_MANIFEST_NAME.toLowerCase()}.js`;
+export const PRODUCT_MANIFEST_FILE_EXT = '.ts';
+export const PRODUCT_MANIFEST_FILE_NAME = `${PRODUCT_MANIFEST_NAME.toLowerCase()}${PRODUCT_MANIFEST_FILE_EXT}`;
 export const PRODUCT_NAME_PLACEHOLDER = 'ProductX';
+/*
+ * Use Case
+ */
 export const UC_DEF_SUFFIX = 'UCD';
 export const UC_DEF_FILE_NAME_EXT = '.ts';
 export const UC_DEF_FILE_NAME_SUFFIX = `${UC_DEF_SUFFIX}${UC_DEF_FILE_NAME_EXT}`;

package/dist/esm/dt/Validation.d.ts

@@ -19,6 +19,14 @@ export declare class Validation {
     get(idx?: NumIndex): [ViolationI18nable, string] | null;
     getViolations(): Violation[];
     getViolationsAsI18nables(): ViolationI18nable[];
+    /**
+     * Check whether the validation has succeeded or not
+     *
+     * If you want to get a violation, use directly {@link get} and check if it's null.
+     * No need to check if `!validation.isOK()` and then call `validation.get()`.
+     *
+     * @returns
+     */
     isOK(): boolean;
     private violationAsI18nable;
 }

package/dist/esm/dt/Validation.js

@@ -24,6 +24,14 @@ export class Validation {
     getViolationsAsI18nables() {
         return this.violations.map((v) => this.violationAsI18nable(v));
     }
+    /**
+     * Check whether the validation has succeeded or not
+     *
+     * If you want to get a violation, use directly {@link get} and check if it's null.
+     * No need to check if `!validation.isOK()` and then call `validation.get()`.
+     *
+     * @returns
+     */
     isOK() {
         return this.violations.length === 0;
     }

package/dist/esm/dt/base/TBase.d.ts

@@ -19,7 +19,8 @@ export interface SemanticsValue {
     color?: Color;
     variant?: SemanticsVariant;
 }
-export type SemanticsMapping = Record<string, SemanticsValue>;
+export type SemanticsMapping = Record<string, // corresponds to T.toString()
+SemanticsValue>;
 export type SemanticsPredicate<T> = (value: T) => SemanticsValue;
 export interface OptionsOpts {
     shouldTranslateLabels?: boolean;

package/dist/esm/dt/base/TBoolean.js

@@ -4,10 +4,12 @@ export class TBoolean extends TBase {
         return 'Boolean';
     }
     assign(raw) {
+        // It's not a string at all
         if (typeof raw !== 'string') {
             super.assign(raw);
             return this;
         }
+        // It's a string, let's try to parse it
         if (raw === 'true') {
             super.assign(true);
             return this;

package/dist/esm/dt/base/TInt.js

@@ -9,15 +9,18 @@ export class TInt extends TNumber {
         return 'Int';
     }
     assign(raw) {
+        // It's not a string at all
         if (typeof raw !== 'string') {
             super.assign(raw);
             return this;
         }
+        // It's a string, let's try to parse it
         const parsed = Number.parseInt(raw, 10);
         if (Number.isNaN(parsed)) {
             super.assign(raw);
             return this;
         }
+        // It's been parsed correctly, let's make sure it's not a float that has been "truncated" into an int
         if (parsed.toString() !== raw) {
             super.assign(raw);
             return this;

package/dist/esm/dt/base/TNumber.js

@@ -18,10 +18,12 @@ export class TNumber extends TBase {
         return 'Number';
     }
     assign(raw) {
+        // It's not a string at all
         if (typeof raw !== 'string') {
             super.assign(raw);
             return this;
         }
+        // It's a string, let's try to parse it
         const parsed = Number.parseFloat(raw);
         super.assign(parsed);
         return this;