docs(tutorial): create todo app tutorial based on tutorial kit (#2213)

* docs(tutorial): create todo app tutorial based on tutorial kit

* chore: action to install tutorial deps

* chore: codeclimate and eslintignore settings

---------

Co-authored-by: Mark Whitfeld <[email protected]>

.codeclimate.yml

@@ -18,6 +18,7 @@ exclude_patterns:
   - 'integrations/'
   - 'integration/'
   - 'tools/'
+  - 'tutorials/'
 ratings:
   paths:
     - 'packages/**/**.ts'

.eslintignore

@@ -1,2 +1,3 @@
 **/*.spec.ts
 packages/store/types/.eslintrc.js
+node_modules/

.github/actions/setup/action.yml

@@ -74,3 +74,7 @@ runs:
     - name: Install project dependencies
       shell: bash
       run: yarn install --frozen-lockfile --non-interactive
+
+    - name: Install tutorials dependencies
+      shell: bash
+      run: yarn --cwd tutorials/create-app/ install --frozen-lockfile --non-interactive

.gitignore

@@ -8,6 +8,7 @@
 **/src/environments/version.ts
 **/builds
 **/@ngxs*
+**/@tutorials*
 
 # dependencies
 **/node_modules
@@ -51,6 +52,8 @@ testem.log
 /dist-lib
 /dist-integration
 **/_ignore
+.astro
+
 
 # testing
 /junit/

tsconfig.base.json

@@ -34,6 +34,7 @@
       "@ngxs/store/internals/testing": ["packages/store/internals/testing/src/index.ts"],
       "@ngxs/store/operators": ["packages/store/operators/src/index.ts"],
       "@ngxs/store/plugins": ["packages/store/plugins/src/index.ts"],
+      "@ngxs/tutorials/create-app": ["tutorials/create-app/src/index.ts"],
       "@ngxs/websocket-plugin": ["packages/websocket-plugin/index.ts"]
     }
   }

tutorials/create-app/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["../../.eslintrc.js"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

tutorials/create-app/README.md

@@ -0,0 +1,3 @@
+# create-app
+
+This library was generated with [Nx](https://nx.dev).

tutorials/create-app/astro.config.ts

@@ -0,0 +1,10 @@
+import tutorialkit from '@tutorialkit/astro';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  outDir: '../../@tutorials/create-app',
+  devToolbar: {
+    enabled: false
+  },
+  integrations: [tutorialkit()]
+});

tutorials/create-app/env.d.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path=".astro/types.d.ts" />
+/// <reference types="@tutorialkit/astro/types" />
+/// <reference types="astro/client" />

tutorials/create-app/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ngxs/create-app-tutorial",
+  "description": "Tutorial that shows how to create an app with @ngxs/store",
+  "type": "module",
+  "scripts": {
+    "astro": "astro",
+    "build": "astro build",
+    "dev": "astro dev",
+    "check": "astro check",
+    "preview": "astro preview",
+    "start": "astro dev"
+  },
+  "dependencies": {
+    "@tutorialkit/components-react": "0.0.1-alpha.23",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.75",
+    "@astrojs/check": "^0.7.0",
+    "@astrojs/react": "^3.5.0",
+    "@iconify-json/ph": "^1.1.12",
+    "@iconify-json/svg-spinners": "^1.1.2",
+    "@tutorialkit/astro": "0.0.1-alpha.23",
+    "@tutorialkit/types": "0.0.1-alpha.23",
+    "@types/node": "^20.12.7",
+    "@unocss/reset": "^0.59.4",
+    "@unocss/transformer-directives": "^0.59.4",
+    "astro": "4.10.2",
+    "fast-glob": "^3.3.2",
+    "prettier-plugin-astro": "^0.13.0",
+    "typescript": "^5.4.5",
+    "unocss": "^0.59.4"
+  }
+}

tutorials/create-app/project.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-app",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "tutorials/create-app/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "serve": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "dev"
+      }
+    },
+    "build": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "build"
+      }
+    },
+    "check": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "check"
+      }
+    }
+  }
+}

tutorials/create-app/src/content/config.ts

@@ -0,0 +1,13 @@
+import { chapterSchema, lessonSchema, partSchema, tutorialSchema } from '@tutorialkit/types';
+import { defineCollection } from 'astro:content';
+
+const tutorial = defineCollection({
+  type: 'content',
+  schema: tutorialSchema
+    .strict()
+    .or(partSchema.strict())
+    .or(chapterSchema.strict())
+    .or(lessonSchema.strict())
+});
+
+export const collections = { tutorial };

tutorials/create-app/src/content/tutorial/1-create-a-todo-app/1-welcome/1-welcome/_files/src/app/todo/todo-list/todo-list.component.ts

@@ -0,0 +1,81 @@
+import { AsyncPipe, NgForOf, NgTemplateOutlet } from '@angular/common';
+import { ChangeDetectionStrategy, Component, inject, Signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { MatButtonModule } from '@angular/material/button';
+import { MatCardModule } from '@angular/material/card';
+import { MatCheckboxModule } from '@angular/material/checkbox';
+import { MatInputModule } from '@angular/material/input';
+import { MatListModule } from '@angular/material/list';
+import { Store } from '@ngxs/store';
+import { TodoItemComponent } from '../components/todo-item/todo-item.component';
+import { TodoModel } from '../types/todo';
+import { signal } from '@angular/core';
+@Component({
+  selector: 'app-todo',
+  templateUrl: './todo-list.component.html',
+  styleUrls: ['./todo-list.component.scss'],
+  standalone: true,
+  imports: [
+    MatInputModule,
+    MatCardModule,
+    MatButtonModule,
+    MatCardModule,
+    MatListModule,
+    MatCheckboxModule,
+    FormsModule,
+    AsyncPipe,
+    NgForOf,
+    NgTemplateOutlet,
+    TodoItemComponent
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class TodoListComponent {
+  private _store = inject(Store);
+
+  completeTodoItems: Signal<TodoModel[]> = signal([
+    {
+      id: 1,
+      title: 'Learn Angular',
+      completed: true
+    },
+    {
+      id: 2,
+      title: 'Learn NGXS',
+      completed: true
+    },
+    {
+      id: 3,
+      title: 'Learn NGXS Store',
+      completed: true
+    },
+    {
+      id: 4,
+      title: 'Learn NGXS Selectors',
+      completed: true
+    },
+    {
+      id: 5,
+      title: 'Learn NGXS Actions',
+      completed: true
+    }
+  ]);
+
+  inCompleteTodoItems: Signal<TodoModel[]> = signal([
+    {
+      id: 6,
+      title: 'Learn NGXS Utility selectors',
+      completed: false
+    }
+  ]);
+
+  newItemName!: string;
+
+  constructor() {}
+
+  toggleItem(todoItem: TodoModel) {}
+
+  addItem() {
+    this.newItemName = '';
+  }
+}

tutorials/create-app/src/content/tutorial/1-create-a-todo-app/1-welcome/1-welcome/content.md

@@ -0,0 +1,27 @@
+---
+type: lesson
+title: Welcome
+focus: /src/app/todo/todo-list/todo-list.component.ts
+---
+
+# Welcome to the NGXS Tutorial!
+
+Let's build a Todo application together while diving into the core concepts of NGXS. This interactive tutorial will guide you through the process of managing your application's state effectively.
+
+By the end of this tutorial, you'll be able to:
+
+- Install NGXS into your Angular project using schematics
+- Understand the fundamental building blocks of NGXS: Actions, State, and Selectors
+- Create a Todo application using NGXS, demonstrating a practical application of these concepts
+
+**We'll start by focusing on Actions as the driving force behind our application.** We'll explore how to:
+
+- Define Actions to represent user interactions and data fetching
+- Update the application's state in response to Actions
+- Create Selectors to efficiently retrieve data from the state
+- Utilize Selectors within your components to display and interact with the state
+
+> This tutorial begins with a static Todo application displayed in the preview panel. Progressively, we'll transform this app into a dynamic, state-managed application.
+> To get familiar with the tutorial, add one incomplete item in the `todo-list-component.ts` file
+
+**Ready to get started?** Let's build!

tutorials/create-app/src/content/tutorial/1-create-a-todo-app/1-welcome/meta.md

@@ -0,0 +1,4 @@
+---
+type: chapter
+title: Welcome
+---

tutorials/create-app/src/content/tutorial/1-create-a-todo-app/2-installation/1-using-schematics/_files/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "ngxs-project",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "ng serve",
+    "build": "ng build"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^18.0.7",
+    "@angular/animations": "^18.0.6",
+    "@angular/cdk": "^18.0.6",
+    "@angular/cli": "^18.0.7",
+    "@angular/common": "^18.0.6",
+    "@angular/compiler": "^18.0.6",
+    "@angular/compiler-cli": "^18.0.6",
+    "@angular/core": "^18.0.6",
+    "@angular/material": "^18.0.6",
+    "@angular/platform-browser": "^18.0.6",
+    "@angular/platform-browser-dynamic": "^18.0.6",
+    "@ngxs/store": "^18.1.1",
+    "rxjs": "~7.8.1",
+    "tslib": "^2.0.0",
+    "zone.js": "~0.14.2"
+  }
+}

tutorials/create-app/src/content/tutorial/1-create-a-todo-app/2-installation/1-using-schematics/content.md

@@ -0,0 +1,37 @@
+---
+type: lesson
+title: Installation using schematics
+focus: /package.json
+---
+
+# Installation
+
+In our Angular application, we should install the `@ngxs/store` using `ng-add` schematic.
+
+> The dependency of NGXS v.18 is Angular >= v.17
+
+The command is:
+
+```bash
+ng add @ngxs/store
+```
+
+This command will update the `package.json` file with the `@ngxs/store` dependency
+
+---
+
+🎧 **Exercises**
+
+- There are no exercises in this lesson
+
+---
+
+👀 **Observe**
+
+- The **package.json** file has the related dependency
+
+---
+
+📚 **Read more**
+
+- Read more in the NGXS documentation about the <a href="https://www.ngxs.io/introduction/installation" target="_blank">installation</a>

tutorials/create-app/src/content/tutorial/1-create-a-todo-app/2-installation/2-create-store/_files/src/app/app.config.ts

@@ -0,0 +1,9 @@
+import { TodoState } from './todo/store/todo.state';
+import { provideHttpClient } from '@angular/common/http';
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { ApplicationConfig } from '@angular/core';
+import { provideStore } from '@ngxs/store';
+
+export const config: ApplicationConfig = {
+  providers: [provideAnimations(), provideHttpClient(), provideStore([])]
+};