Getting up-to-date.

content/react/_index.md

@@ -0,0 +1,216 @@
++++
+title = "React Notes"
+description = "Basic documentation for React"
+date = 2022-06-22T18:00:00+00:00
+updated = 2022-06-22T18:00:00+00:00
+template = "section.html"
+sort_by = "weight"
+weight = 6
+draft = false
+[taxonomies]
+documentation=["Reference"]
+categories=["React", "single-page-applications"]
++++
+
+[React](https://reactjs.org/) is a Javascript library for creating dynamic and
+responsive websites.  It is the most popular of the current generation of SPA
+(Single Page Application) tools, and it's the one I use professionally.
+
+## Starting a project
+
+React is installed using [npm](https://npmjs.com). You have three principle
+choices when it comes to installing React: You can install it the basic way by
+creating a new project folder and running `npm install react react-dom` (the
+latter is for web-based projects rather than `react-native` projects for Android
+and IOs), you can use a project template (my preferred technique, but it
+requires routine updating), and using
+[create-react-app](https://create-react-app.dev), which includes an entire
+framework for React, including a hot-loader for development, pre-configured
+tooling for ESLint, Prettier, and a host of other code-quality features.
+
+Personally, I have always found that create-react-app is limiting in too many
+ways; eventually, I end up not even using the CRA "eject" feature (which
+converts the implicit configuration hidden in the `node_modules` folder into
+explicit configuration); instead, I create a new project, copy the `src` folder
+from the CRA project into that, and construct a new toolchain around it, one
+that isn't cluttered by all the other things found in CRA and one that is
+configured to my exact specficiation.
+
+## A Mental Model for React
+
+[Caveat: This is a mental model for *React*.  Once you start adding a whole
+bunch of tooling on top of React, you're on your own.]
+
+A React application has a collection of one or more *states*.  A complex
+application may have orthoganal states: the user's identity, tracking the page
+they're currently looking at, one or more forms the customer has interact with,
+and so on.  React listens to these states and, where you have specified that a
+state change has a consequential visual change on the page, React automatically
+updates the page.
+
+All input from React should be channeled up to the aggregate collection of
+states, and your React app should be written such that it correctly responds to
+that change.  It's a singular loop with no internal contradictions.
+
+React creates a tree internally that describes the visual result of the current
+state.  When you update the state, that tree is rebuilt, compared to the
+previous version, and only those parts of the HTML that are directly affected
+are updated.
+
+Never forget: React's output is a tree. React's behavior is an event loop. React
+is a recursive engine operating on a recursive data structure, it manipulates
+another recursive data structure (the browser's Document Object Model, or DOM),
+and success depends upon *your* data being able to fit into that exact same
+model.
+
+## JSX
+
+``` typescript
+import React from "react";
+import ReactDOM from "react-dom";
+
+const Hello = <h1>Hello, World!</h1>;
+const root = ReactDOM.createRoot(document.getElementById('root'));
+root.render(<Hello />);
+```
+
+This is the smallest possible React program that shows React and JSX.  JSX is an
+XML-like addition that you write directly into your Javascript.  All JSX
+functions begin with a capital letter, to distinguish from plain old HTML, which
+is always begun with a lower case letter.  That `Hello` is a function; under the
+covers, the JSX parser turns it into a bit of code that generates the HTML and,
+if specified, hooks up event handlers.
+
+
+
+
+
+
+
+Git is project and folder-centered, and to start using git go to the root folder
+of a project you want to place under source control and initialize it:
+
+```bash
+$ mkdir a-new-project
+$ touch README.md
+$ git init
+```
+
+This creates a new folder, `.git`, where Git will store your commit history and
+some configuration details.  Git will usually not create a repository without
+_something_ to store in it, but see the [`git start` alias](#config) below.
+    
+## Putting files into git
+
+To put files under source control, you must add them.  To update the entire
+folder, switch to the root of the project and add _all_ of it:
+
+```bash
+$ git add .
+$ git commit
+```
+
+An editor will pop-up, asking you what this commit is about.  It's generally
+polite, especially if you're working in a team, to explain your commit in some
+detail-- and to generally keep the commit small, in order to ensure that you
+don't have to explain too much!
+
+If your commit message could be a single line, you can add it directly from the
+command line:
+
+```bash
+$ git add .
+$ git commit -m "Updated the widget to widgetize."
+```
+
+... and you can even combine both commands, but be careful: this command will
+not add any files that are new. It will only commit existing files that have
+been modified, and will delete any files that you have deleted, from the
+repository. (Deleted files still exist in the history and can always be
+recovered.)
+
+```bash
+$ git commit -am "Updated the widget to widgetize."
+```
+
+## Git Configuration {#config}
+
+You can have a global Git configuration file, `$HOME/\.gitconfig`, in which you
+keep your personal information and command aliases, which is one of three ways
+you can add your own commands to Git.
+
+```bash
+[user]
+    name = Elf M. Sternberg
+    email = someguy@example.com
+    
+[alias]
+    unstage = reset -q HEAD --
+    nevermind = !git reset --hard HEAD && git clean -d -f
+	wip = for-each-ref --sort='authordate:iso8601' --format='%(color:green)%(authordate:relative)%09%(color:white)%(refname:short)' refs/heads	
+    stem = "!f() { git checkout -b $1 develop; }; f"
+    start = !git init && git commit --allow-empty -m \"Initial commit\"
+```
+
+## Git Aliases {#aliases}
+
+Aliases are commands that you can run *in git* as if they were part of the git
+toolset, but their functionality is defined by you.  The five aliases shown
+above are my "must haves."  They represent the way I work.
+
+- `unstage` is something I do a lot.  Maybe it's my ADHD, but I often add
+  something to the git staging area, then realize that the work was incomplete
+  and have to go back.  This command does that, and I hated memorizing it.
+- `nevermind` is for when your work has gone off the rails; your stab at solving
+  the problem has taken you places you didn't want to be.  This command resets
+  you to exactly where you were before you started hacking.
+- `wip` stands for "works in progress"; it shows you a list of branches
+  currently live in your local project, in the order from oldest to newest, with
+  a text that tells you your last commit was "yesterday" or "3 months ago".
+- `stem` creates a new branch off the develop branch (you can change that to
+  main or canon or whatever). This is the most common workflow I have at home,
+  and this command allows me to get to it quickly. The syntax tells git to use
+  the bash to populate the new branch name, as the default alias format can
+  only take arguments at the end, and the new branch name must be injected
+  before the source branch.
+- `start` creates a git repository out of a completely empty folder.  This might
+  seem odd, but it's actually a very useful way of introducing a new project and
+  ensuring git is ready to go.
+
+## Git Extensions
+
+Just like aliases, you can add whole unique commands to git, as long as the
+extension name doesn't conflict with one of git's internal commands.  The
+syntax for doing so is to create a script (in any language!) and name it
+`git-your-extension-name`, and you call it by invoking git and giving it the
+extension name. 
+
+For example, if you write documentation and you want to know how many words
+you've written since your last commit, you can create a Bash script named
+`git-wc` (word count):
+
+``` bash
+#!/bin/bash
+REM=`git diff --word-diff=porcelain -U $* | grep '^-' | sed 's/^-//' | wc -w`
+ADD=`git diff --word-diff=porcelain -U $* | grep '^+' | sed 's/^+//' | wc -w`
+DIF=`expr $ADD - $REM`
+echo "Word count: $DIF"
+```
+
+## Add vs Commit
+
+You may have noticed that there's a two-step to committing your work; you `add`
+it, then `commit` it.  `add`ing it puts it into the `staging area`.  The primary
+goal of this design is to allow you to commit only parts of your project, rather
+than committing everything at once.  By creating an index of what-to-commit, and
+then allowing you to write your commit message afterward, you have more control
+over the development process.
+
+If you're completely reassured of your skillz as a _leet koder dood_, you could
+always create an alias that stages, commits, and pushes to your remote
+repository all at once.  I don't recommend that.
+
+
+    
+
+