Fix #82: Providing the motivation and how to use this guide

.gitignore

@@ -39,3 +39,5 @@ jspm_packages
 temp/
 playground/dist
 playground/storybook-static
+
+CLAUDE.md

README.md

@@ -35,6 +35,29 @@ _Found it useful? Want more updates?_
 - Make type annotations concise by eliminating redundancy in types using advanced TypeScript Language features like **Type Inference** and **Control flow analysis**
 - Reduce repetition and complexity of types with TypeScript focused [complementary libraries](#react-redux-typescript-ecosystem)
 
+### **What This Guide Is**
+
+This repository is a reference guide and recipe collection for using React, Redux, and TypeScript together. It is **not** a boilerplate, starter kit, or library that introduces its own replacement APIs for React.
+
+Most of the types shown in this guide come from the official React and React Redux type packages such as `@types/react` and `@types/react-redux`. When you see names like `React.FC`, `React.ComponentType`, or `React.ReactNode`, they are existing React types that this guide explains and uses in examples.
+
+### **How to Use This Guide**
+
+If you are new to React, read this guide in the following order:
+
+1. Start with the [Playground Project](#playground-project) to see where the examples live.
+2. Read the [React Types Cheatsheet](#react-types-cheatsheet) before diving into the component recipes.
+3. Work through the [React](#react) section from top to bottom, then move on to [Redux](#redux).
+4. Use later sections like [Configuration & Dev Tools](#configuration--dev-tools) and [FAQ](#faq) as reference material when you need them.
+
+If you already know React, you can treat each section as an independent recipe and jump directly to the pattern you need.
+
+### **Understanding the Playground and Style Guide**
+
+The `/playground` folder is the runnable sample app for this repository. The examples shown on the home page come from files such as `*.usage.tsx`, and the app route in `playground/src/routes/home.tsx` stitches those usage examples together into one screen.
+
+The Styleguidist demo is a separate view over the same source files. It renders markdown docs and live examples from `playground/src`, organized by `playground/styleguide/styleguide.config.js`. That is why the browser output can look different from the `/playground` app even though both are driven by the same example components.
+
 ### **React, Redux, Typescript Ecosystem**
 
 - [typesafe-actions](https://github.com/piotrwitek/typesafe-actions) - Typesafe utilities for "action-creators" in Redux / Flux Architecture  
@@ -76,6 +99,9 @@ I highly recommend to add a bounty to the issue that you're waiting for to incre
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 
+  - [What This Guide Is](#what-this-guide-is)
+  - [How to Use This Guide](#how-to-use-this-guide)
+  - [Understanding the Playground and Style Guide](#understanding-the-playground-and-style-guide)
   - [React Types Cheatsheet](#react-types-cheatsheet)
     - [`React.FC<Props>` | `React.FunctionComponent<Props>`](#reactfcprops--reactfunctioncomponentprops)
     - [`React.Component<Props, State>`](#reactcomponentprops-state)

README_SOURCE.md

@@ -35,6 +35,29 @@ _Found it useful? Want more updates?_
 - Make type annotations concise by eliminating redundancy in types using advanced TypeScript Language features like **Type Inference** and **Control flow analysis**
 - Reduce repetition and complexity of types with TypeScript focused [complementary libraries](#react-redux-typescript-ecosystem)
 
+### **What This Guide Is**
+
+This repository is a reference guide and recipe collection for using React, Redux, and TypeScript together. It is **not** a boilerplate, starter kit, or library that introduces its own replacement APIs for React.
+
+Most of the types shown in this guide come from the official React and React Redux type packages such as `@types/react` and `@types/react-redux`. When you see names like `React.FC`, `React.ComponentType`, or `React.ReactNode`, they are existing React types that this guide explains and uses in examples.
+
+### **How to Use This Guide**
+
+If you are new to React, read this guide in the following order:
+
+1. Start with the [Playground Project](#playground-project) to see where the examples live.
+2. Read the [React Types Cheatsheet](#react-types-cheatsheet) before diving into the component recipes.
+3. Work through the [React](#react) section from top to bottom, then move on to [Redux](#redux).
+4. Use later sections like [Configuration & Dev Tools](#configuration--dev-tools) and [FAQ](#faq) as reference material when you need them.
+
+If you already know React, you can treat each section as an independent recipe and jump directly to the pattern you need.
+
+### **Understanding the Playground and Style Guide**
+
+The `/playground` folder is the runnable sample app for this repository. The examples shown on the home page come from files such as `*.usage.tsx`, and the app route in `playground/src/routes/home.tsx` stitches those usage examples together into one screen.
+
+The Styleguidist demo is a separate view over the same source files. It renders markdown docs and live examples from `playground/src`, organized by `playground/styleguide/styleguide.config.js`. That is why the browser output can look different from the `/playground` app even though both are driven by the same example components.
+
 ### **React, Redux, Typescript Ecosystem**
 
 - [typesafe-actions](https://github.com/piotrwitek/typesafe-actions) - Typesafe utilities for "action-creators" in Redux / Flux Architecture  
@@ -76,6 +99,9 @@ I highly recommend to add a bounty to the issue that you're waiting for to incre
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 
+  - [What This Guide Is](#what-this-guide-is)
+  - [How to Use This Guide](#how-to-use-this-guide)
+  - [Understanding the Playground and Style Guide](#understanding-the-playground-and-style-guide)
   - [React Types Cheatsheet](#react-types-cheatsheet)
     - [`React.FC<Props>` | `React.FunctionComponent<Props>`](#reactfcprops--reactfunctioncomponentprops)
     - [`React.Component<Props, State>`](#reactcomponentprops-state)

package.json

@@ -5,8 +5,9 @@
     "husky": "3.0.9"
   },
   "scripts": {
-    "ci-check": "npm run doctoc && npm run readme:generate",
-    "doctoc": "doctoc --maxlevel=3 README_SOURCE.md",
+    "test": "node --test test/*.test.js",
+    "ci-check": "npm run readme:generate && npm test",
+    "doctoc": "node -e \"console.log('README_SOURCE.md TOC is maintained in source for this repository.')\"",
     "readme:generate": "node generate-readme.js",
     "contributors:check": "all-contributors check",
     "contributors:add": "all-contributors add",

playground/README.md

@@ -1 +1,8 @@
 This folder is a playground project for testing the code examples that can be found in the guide. They are all tested with the most recent supported version of TypeScript and third-party type-definitions (like `@types/react` or `@types/react-redux`) to ensure the examples are still working when new third-party type-definitions are released.
+
+The playground app and the style guide are two different ways of browsing the same examples:
+
+- `src/routes/home.tsx` renders the example `*.usage.tsx` files into the app home page.
+- `styleguide/styleguide.config.js` organizes selected components and markdown docs into the Styleguidist site.
+
+If the browser output looks different between those two views, that is expected. They share source files, but they assemble and present them differently.

playground/styleguide/docs/intro.md

@@ -1,3 +1,8 @@
 ### Styleguide
 
+This style guide is a documentation view over the examples in `/playground/src`.
+
+The sections and component list come from `playground/styleguide/styleguide.config.js`.
+The rendered examples are loaded from the same component, markdown, and usage files that power the playground app, so this page may look different from `/playground/src/routes/home.tsx` while still using the same source material.
+
 [⇦ back to guide](https://github.com/piotrwitek/react-redux-typescript-guide#table-of-contents)

test/readme-onboarding.test.js

@@ -0,0 +1,45 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const readmePath = path.join(__dirname, '..', 'README.md');
+const readme = fs.readFileSync(readmePath, 'utf8');
+
+test('README explains what the guide is and is not', () => {
+  assert.match(
+    readme,
+    /### \*\*What This Guide Is\*\*/
+  );
+  assert.match(
+    readme,
+    /This repository is a reference guide and recipe collection for using React, Redux, and TypeScript together\./
+  );
+  assert.match(
+    readme,
+    /It is \*\*not\*\* a boilerplate, starter kit, or library that introduces its own replacement APIs for React\./
+  );
+});
+
+test('README gives beginners a reading path and clarifies the styleguide', () => {
+  assert.match(
+    readme,
+    /### \*\*How to Use This Guide\*\*/
+  );
+  assert.match(
+    readme,
+    /Start with the \[Playground Project\]\(#playground-project\) to see where the examples live\./
+  );
+  assert.match(
+    readme,
+    /### \*\*Understanding the Playground and Style Guide\*\*/
+  );
+  assert.match(
+    readme,
+    /The Styleguidist demo is a separate view over the same source files\./
+  );
+  assert.match(
+    readme,
+    /It renders markdown docs and live examples from `playground\/src`, organized by `playground\/styleguide\/styleguide\.config\.js`\./
+  );
+});