@nutin/cli 1.3.1 → 2.0.0

package/templates/base/GETTING_STARTED.md.hbs

@@ -0,0 +1,227 @@
+# Getting started
+
+## Table of contents
+
+- [Project structure](#project-structure)
+- [Running your app](#running-your-app)
+- [Generate components, views and services](#generate-components-views-and-services)
+- [A typical component](#a-typical-component)
+- [Features and configuration](#features-and-configuration)
+- [Styling](#styling)
+- [Global layout components](#global-layout-components)
+- [Testing](#testing)
+- [Useful links](#useful-links)
+
+## Project structure
+
+```
+config/   -- configure i18n and SEO files
+
+src/
+  app/
+    components/
+    services/
+    views/
+    routes.ts
+    main.ts
+  assets/
+  core/   -- Nutin framework source
+  styles/
+
+tools/    -- build, development, generator and testing
+
+nutin.config.js   -- features and configuration
+```
+
+## Running your app
+
+```bash
+# Development
+{{packageManager}} run serve # build and serve
+{{packageManager}} run dev   # build and serve with live reload
+
+# Build
+{{packageManager}} run build      # build the application
+{{packageManager}} run build:prod # build the application for production
+```
+
+### Imports
+
+Imports must use **relative paths** and end with `.js` extension.
+
+```js
+import { Foo } from 'relative/path/to/foo.js';
+```
+
+## Generate components, views and services
+
+Generated elements are automatically exported from the corresponding barrel file:
+`src/app/<components|views|services>/index.ts`.
+
+
+```bash
+{{packageManager}} run generate <component|view|service> ELEMENT_NAME
+
+# Examples
+{{packageManager}} run generate component my-component # Target dir: src/app/components/my-component/
+{{packageManager}} run generate component path/to/my-component/ # Target dir: src/app/components/path/to/my-component/
+```
+
+## A typical component
+
+```bash
+components/
+  product-card/
+    product-card.component.html
+    product-card.component.scss
+    product-card.component.ts
+```
+
+```ts
+// The builder injects the component's .html template here.
+const templateFn = (product: Product) => `__TEMPLATE_PLACEHOLDER__`;
+
+export class ProductCardComponent extends Component {
+  private _product: Product;
+
+  constructor(mountTarget: HTMLElement, config: Product) {
+    super({ templateFn, mountTarget, config });
+    this._product = config;
+  }
+
+  // Declares children mounted into the data-component / data-catalog placeholders below.
+  public registerChildren(): ComponentConfig[] {
+    // Single child, matched to <div data-component="product-details">
+    const detailsComponent = {
+      selector: `product-details`,
+      factory: (el) => new ProductDetailsComponent(
+        el, 
+        { config: this._product.details },
+      )
+    };
+
+    // One child per item in _product.tags, matched to <div data-catalog="product-tags">
+    const tagsCatalog = this.createCatalogComponents({
+      selector: 'product-tags',
+      items: this._product.tags,
+      component: ProductTagsComponent,
+      elementName: 'product-tag'
+    });
+
+    return [
+      detailsComponent,
+      ...tagsCatalog
+    ];
+  }
+
+  // Referenced by the data-event attribute in the template.
+  private _goToProductPage(productId: string): void {
+    Navigation.navigateTo(`/product/${productId}`);
+  }
+}
+```
+
+```html
+<div
+  data-event="click:_goToProductPage:${product.id}"
+  class="product-card"
+>
+  <h2 class="product-card__name">${product.name}</h2>
+  <div data-component="product-details"></div>
+  <div data-catalog="product-tags"></div>
+</div>
+```
+
+```scss
+.product-card {
+  // component styles
+}
+
+.product-card__name {
+  // element styles
+}
+```
+
+A template can also be written directly inline (skip the `.html` file and the placeholder). 
+
+Defining both an inline template and an external `.html` file, or neither, fails the build.
+
+## Features and configuration
+
+Nutin features are enabled in `nutin.config.js`.
+
+### `nutin.config.js`
+
+Main Nutin configuration and tool options. See the inline comments for details.
+
+- `tailwind`, `i18n`, `generateSEOFiles` — top-level features, `false` by default.
+- `generator.*` — controls what the generator scaffolds.
+- `builder.*` — controls build behavior.
+- `testinNutin.*` — controls TestinNutin.
+
+### `config/seo.json`
+
+- Register your routes' description, title and ogImage here.
+- Data is used to generate static `index.html` per route, `robots.txt`, and `sitemap.xml`.
+- Unused if `nutin.config.js -> generateSEOFiles` is disabled.
+
+### `config/languages.json`
+
+- Register supported languages for i18n here.
+- Unused if `nutin.config.js -> i18n` is disabled.
+
+## Styling
+
+- Nutin uses SASS (`.scss` syntax, compatible with plain CSS) as its default styling solution.
+
+- Tailwind CSS v4 is also supported as an optional utility-first CSS layer.
+
+**Note:** Installing Tailwind CSS dependencies may print `npm warn install-scripts`. This is expected with npm 12's default install-script allowlisting and is safe to ignore.
+
+## Global layout components
+
+If you need components to render outside `<main>` (such as a header or footer), register them with `registerGlobals()` in `main.ts` constructor.
+
+Global components are mounted directly in `<body>` and remain present across route changes. Use `before` for components that should appear before `<main>` and `after` for components that should appear after it.
+
+```ts
+registerGlobals({
+  before: [{ component: HeaderComponent, id: 'header' }],
+  after: [{ component: FooterComponent, id: 'footer' }],
+});
+```
+
+**Note**: `hideGlobals(globalIds: string[])` / `revealGlobals(globalIds: string[])` are exported alongside `registerGlobals` and can be called to toggle visibility of the ids you registered.
+
+## Testing
+
+You can use any testing tool you prefer for application code.
+
+This project includes TestinNutin, Nutin's lightweight testing toolkit. Nutin itself is tested exclusively with it, and the tests are included in the generated project so you can:
+- use them as executable documentation;
+- run and modify Nutin's tests when modifying its code.
+
+Run the tests with:
+
+`{{packageManager}} run testin-nutin`
+
+To use TestinNutin for application tests, enable:
+
+```js
+// nutin.config.js
+testinNutin: {
+  includeApp: true,
+}
+```
+*Note:* TestinNutin files use root imports.
+```js
+import { MyModule } from '#root/dist/src/path/to/my-module.js';
+```
+
+See **[TestinNutin docs](https://nutin.org/docs/testin-nutin)**.
+
+## Useful links
+
+- [Nutin website](https://www.nutin.org)
+- [First app tutorial](https://www.nutin.org/tutorial)
+- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs)

package/templates/base/README.md.hbs

@@ -1,24 +1,15 @@
-# {{projectName}} - Built with nutin
+# {{projectName}} - Built with Nutin
 
-## Start
+## Development
 
-- `{{packageManager}} run serve` (rebuild), `{{packageManager}} run serve:only` (no rebuild), `{{packageManager}} run dev` (watch).
+- `{{packageManager}} run serve` — build and serve
+- `{{packageManager}} run dev` — build and serve with live reload
 
 ## Build
 
-- `{{packageManager}} run build` (dev) or `{{packageManager}} run build:prod` (production)
+- `{{packageManager}} run build` — build the application
+- `{{packageManager}} run build:prod` — build the application for production
 
-	Accepts `--bundle` (= build:prod) and `--log` (verbose output) flags
+## Getting started
 
-## Generate Component, View, Service
-
-- `{{packageManager}} run generate ELEMENT ELEMENT_NAME`
-
-	Supports nested paths.
-
-{{#if testinNutin}}
-## Test
-
-- `{{packageManager}} run test:rebuild`, `{{packageManager}} run test`, `{{packageManager}} run test:watch`.
-
-{{/if}}
+See [Getting Started](GETTING_STARTED.md) for project-specific guidance.

package/templates/base/config/languages.json.hbs

@@ -0,0 +1,6 @@
+{
+  "languages": [
+    "en"
+  ],
+  "defaultLanguage": "en"
+}

package/templates/base/config/seo.json.hbs

@@ -0,0 +1,12 @@
+{
+  "baseUrl": "https://my-website.com",
+  "disallowBots": [],
+  "routes": [
+    {
+      "path": "/",
+      "title": "{{projectName}}",
+      "description": "{{projectName}}",
+      "ogImage": "/assets/images/og-cover.jpg"
+    }
+  ]
+}

package/templates/base/nutin.config.js.hbs

@@ -0,0 +1,51 @@
+export default {
+  // Nutin options
+  tailwind: false,         // Enable Tailwind CSS v4
+  i18n: false,             // Enable i18n; configure languages in config/languages.json
+  generateSEOFiles: false, // Generate per-route HTML, robots.txt and sitemap.xml; configure SEO data in config/seo.json
+  
+  // Components / Views scaffolding
+  generator: {
+    generateStylesheet: false, // Generate a .scss file alongside each component or view
+    generateLocales: false,    // Generate locale files alongside components and views (requires i18n)
+    generateTest: false,       // Generate test files alongside components, views and services (requires testinNutin.includeApp)
+  },
+
+  // Build pipeline
+  builder: {
+    sass: {
+      paths: [ 
+        'base', 
+      ], // Directories in styles/ to include in the Sass load path
+    },
+
+    esbuild: {
+      bundle: true,
+      minify: true,
+      sourcemap: false,
+      target: ['es2015'],
+      drop: ['console', 'debugger'],
+    },
+  },
+
+  // Testing toolkit
+  // `{{packageManager}} run testin-nutin`
+  testinNutin: {
+    includeFramework: true,  // Test Nutin source - src/core
+    includeTools: false,     // Test tools/ (builder, testin-nutin, etc.)
+    includeApp: false,       // Include application tests
+
+    coverage: {
+      enabled: false,        // Include coverage in the normal test command
+      threshold: 95,         // Fail if any global coverage metric falls below this threshold
+      reportUncovered: true, // Generate a report of uncovered lines, functions and branches
+    },
+
+    jsdomOptions: {
+      runScripts: false,
+      resources: false,
+      freezeGlobals: false,
+      pretendToBeVisual: true,
+    },
+  },
+}

package/templates/base/src/app/components/index.ts.hbs

@@ -1,2 +1 @@
-export * from './common/button/button.component.js';
-export * from './common/anchor/anchor.component.js';
+// global components export

package/templates/base/src/app/globals.d.ts.hbs

@@ -1,20 +1,4 @@
-declare type CoreEventMap = {
-    'navigate': string;
-    'reload': string;
-    'view-mount': string;
-    'view-render': string;
-    'view-unmount': string;
-    'track-pageview': { page: string };
-    'popover-opened': string;
-    'popover-close': string;
-    {{#if i18n}}
-    'language-changed': string;
-    {{/if}}
-    // Add other events and their payload types here
+declare interface AppEventMap {
+    // Add app-specific event types here
+    // 'event': { /* payload? */ }
 };
-
-declare type StoreEventMap = {[ K in `store:${string}` ]: any; };
-
-// Merged event map
-declare type EventMap = CoreEventMap & StoreEventMap;
-declare type EventKey = keyof EventMap;

package/templates/base/src/{libs/guards → app}/guards.ts.hbs

@@ -1,10 +1,6 @@
-import { RouteGuard } from "../../core/index.js";
+import { RouteGuard } from "../core/index.js";
 
 export const Guards = {
-  custom: (checkFn: () => boolean | string | Promise<boolean | string>, redirectTo?: string): RouteGuard => {
-    return checkFn || redirectTo;
-  },
-
   /**
    * Basic example
    */

package/templates/base/src/app/main.ts.hbs

@@ -1,39 +1,20 @@
-import { AppRouter, Service{{#if i18n}}, I18nService{{/if}} } from '../core/index.js';
-import { registerPipes } from '../libs/index.js';
+import nutinConfig from '../../nutin.config.js';
+import { AppRouter, Service, I18nService, registerPipes } from '../core/index.js';
 import { appRoutes } from './routes.js';
 
 class App {
-  // private header: NavbarComponent;
-
   constructor() {
     registerPipes();
     AppRouter(appRoutes);
-
-    // Init global components
-    // this.header = new NavbarComponent('body' as unknown as HTMLElement);
-    // this.footer = new FooterComponent('body' as unknown as HTMLElement);
-
-    // Init app
-    this.initialize();
-  }
-
-  public async initialize() {
-    this.renderBaseLayout();
-  }
-
-  private renderBaseLayout() {
-    // e
-    // document.body.prepend(this.header.render());
-    // document.body.append(this.footer.render());
   }
 }
 
 document.addEventListener('DOMContentLoaded', async () => {
-  {{#if i18n}}
-  await I18nService.initTranslations();
-  await I18nService.loadTranslations(I18nService.currentLanguage);
-  {{/if}}
-  const app = new App();
+  if (nutinConfig.i18n) {
+    await I18nService.initTranslations();
+    await I18nService.loadTranslations(I18nService.currentLanguage);
+  }
+  new App();
 });
 
 window.addEventListener('beforeunload', async () => {

package/templates/base/src/app/services/index.ts.hbs

@@ -1 +1 @@
-export * from './example/example.service.js';
+// global services export

package/templates/base/src/app/views/home/home.view.html.hbs

@@ -0,0 +1,7 @@
+<div style="display:flex;justify-content:center;align-items:center;flex-direction:column;padding-top:clamp(1rem,3vw,2rem);padding-bottom:clamp(1rem,3vw,2rem);">
+  <h1 style="color:#6C8359;font-size:clamp(1.5rem,5vw,2.5rem);font-weight:bold;">{{projectName}}</h1>
+  <span style="font-style:italic;font-size:clamp(.6875rem,2vw,1rem);">nutin v{{version}}</span>
+  <img src="/assets/images/logo-trans.avif" width=250 height=250 alt="nutin's logo. A frame opened on the top left through which a plant grows.">
+  <div style="color:#C56648;font-size:clamp(1.125rem,4vw,1.5rem);">Happy Coding 🎉</div>
+  <div style="font-size:clamp(.75rem,2vw,1rem);font-style:italic;position:fixed;bottom:0;">so lightweight it's <span style="font-weight:bold;">nutin</span>.</div>
+</div>

package/templates/base/src/app/views/home/home.view.ts.hbs

@@ -1,61 +1,6 @@
 import { View } from '../../../core/index.js';
 
-const template = `{{#if template}}__TEMPLATE_PLACEHOLDER__{{else}}<div 
-{{#if stylinNutin}}
-  class="u-flex-center u-flex-column u-padd-y-large"
-{{else}}
-  style="display:flex;justify-content:center;align-items:center;flex-direction:column;padding-top:1rem;padding-bottom: 1rem;"
-{{/if}}>
-  <h1 
-  {{#if i18n}}
-    data-i18n="home.title"
-  {{/if}} 
-  {{#if stylinNutin}}
-    class="u-color-prim u-font-largest u-bold u-font-secondary"
-    style="color:#6C8359;"
-  {{else}}
-    style="color:#6C8359;font-size:2rem;font-weight:bold;"
-  {{/if}}
-  >{{#unless i18n}}{{projectName}}{{/unless}}</h1>
-  <span 
-  {{#if stylinNutin}}
-    class="u-italic u-font-smallest u-font-secondary"
-  {{else}}
-    style="font-style:italic;font-size:0.75rem;"
-  {{/if}}
-  >nutin v{{version}}</span>
-  <img src="/assets/images/logo-trans.avif" width=250 height=250 alt="nutin's logo. A frame opened on the top left through which a plant grows.">
-  <div 
-  {{#if i18n}}
-    data-i18n="home.ready" 
-  {{/if}}
-  {{#if stylinNutin}}
-    class="u-font-large u-padd-y-medium" 
-    style="margin-top:-2rem;"
-  {{else}}
-    style="font-size:1.5rem;paddin-top:1rem;padding-bottom:1rem;margin-top:-2rem;"
-  {{/if}}
-  >{{#unless i18n}}You're all set !{{/unless}}</div>
-  <div 
-  {{#if i18n}}
-    data-i18n="home.enjoy" 
-  {{/if}}
-  {{#if stylinNutin}}
-    class="u-font-large u-color-sec"
-    style="color:#C56648;"
-  {{else}}
-    style="color:#C56648;font-size:1.5rem;"
-  {{/if}}
-  >{{#unless i18n}}Happy Coding 🎉{{/unless}}</div>
-  <div 
-  {{#if stylinNutin}}
-    class="u-italic u-font-secondary u-font-small" 
-    {{#unless transition}}style="position:fixed;bottom:0;"{{/unless}}
-  {{else}}
-    style="font-size:.875rem;font-style:italic;{{#unless transition}}position:fixed;bottom:0;{{/unless}}"
-  {{/if}}
-  >so lightweight it's <span {{#if stylinNutin}}class="u-bold"{{else}}style="font-weight:bold;"{{/if}}>nutin</span>.</div>
-</div>{{/if}}`;
+const template = `__TEMPLATE_PLACEHOLDER__`;
 
 export class HomeView extends View {
   constructor() {

package/templates/base/src/app/views/index.ts.hbs

@@ -1,2 +1,3 @@
+// global views export
 export * from './home/home.view.js';
 export * from './not-found/not-found.view.js';

package/templates/base/src/app/views/not-found/not-found.view.html.hbs

@@ -0,0 +1,8 @@
+<div style="display:flex;justify-content:center;align-items:center;flex-direction:column;padding-top:clamp(1rem,5vw,2rem);">
+  <h1 style="font-size:clamp(2rem,8vw,3rem);font-weight:bold;">Page Not Found</h1>
+  <img src="/assets/images/logo-small-trans.avif" width=250 height=250 alt="nutin's small logo with a growing plant.">
+  <button 
+    data-event="click:_handleHome" 
+    style="background-color:inherit;font-size:clamp(1.25rem,5vw,2rem);font-style:italic;padding-top:clamp(.75rem,2vw,1rem);padding-bottom:clamp(.75rem,2vw,1rem);text-decoration:underline;"
+  >Go back</button>
+</div>

package/templates/base/src/app/views/not-found/not-found.view.ts.hbs

@@ -1,46 +1,13 @@
-import { AppEventBus, ComponentConfig, View } from '../../../core/index.js';
-import { ButtonComponent } from '../../components/index.js';
+import { Navigation, View } from '../../../core/index.js';
 
-const template = `{{#if template}}__TEMPLATE_PLACEHOLDER__{{else}}<div 
-{{#if stylinNutin}}
-  class="u-flex-center u-flex-column u-padd-y-large"
-{{else}}
-  style="display:flex;justify-content:center;align-items:center;flex-direction:column"
-{{/if}}>
-  <h1 
-  {{#if i18n}}
-    data-i18n="not-found.content" 
-  {{/if}}
-  {{#if stylinNutin}}
-    class="u-color-sec u-font-largest u-bold u-font-secondary"
-  {{else}}
-    style="font-size:2rem;font-weight:bold;"
-  {{/if}}
-  >{{#unless i18n}}Page Not Found{{/unless}}</h1>
-  <img src="/assets/images/logo-small-trans.avif" width=250 height=250 alt="nutin's small logo with a growing plant.">
-  <div data-component="home"></div>
-</div>{{/if}}`;
+const template = `__TEMPLATE_PLACEHOLDER__`;
 
 export class NotFoundView extends View {
   constructor() {
     super({template});
   }
 
-  childConfigs(): ComponentConfig[] {
-    {{#if stylinNutin}}
-    const btnClass = 'u-bg-inherit u-font-large u-padd-y-medium u-color-prim u-italic';
-    {{else}}
-    const btnStyles = 'background-color:inherit;font-size:large;font-style:italic;padding-top:1rem;padding-bottom:1rem;'
-    {{/if}}
-    return [
-      { 
-        selector: 'home',
-        factory: (el) => new ButtonComponent(el, { {{#if i18n}}i18nKey: 'not-found.redirect'{{else}}textContent: 'Back to home'{{/if}}, callback: () => this.handleHome(), {{#if stylinNutin}}className: btnClass{{else}}style: btnStyles{{/if}} })
-      },
-    ]
-  }
-
-  handleHome() {
-    AppEventBus.emit('navigate', '/');
+  private _handleHome(): void {
+    Navigation.navigateTo('/');
   }
 }