Fundamentals — Cheat Sheet

The Mental Model — UI as a Function of State

// Imperative — you perform each transition yourself
function showResults(results) {
  spinner.style.display = 'none'
  errorBox.style.display = 'none'
  list.innerHTML = ''
  results.forEach(r => list.append(makeRow(r)))
  emptyState.style.display = results.length ? 'none' : 'block'
}
// Every new state means auditing every branch again.

// Declarative — you describe the destination for each state
function Results({ status, results, error }) {
  if (status === 'loading') return <Spinner />
  if (status === 'error')   return <ErrorBox message={error} />
  if (results.length === 0) return <EmptyState />
  return <ul>{results.map(r => <Row key={r.id} {...r} />)}</ul>
}
// Add a state and the compiler and the reader both see the gap.

JSX — Markup That Is Really JavaScript

// You write
<button className="primary" onClick={handleRun}>Run</button>

// The compiler produces
jsx('button', { className: 'primary', onClick: handleRun, children: 'Run' })

// which evaluates to a plain object describing what to render:
{ type: 'button', props: { className: 'primary', ... } }

// Consequences that follow directly:
//   - 'class' is a reserved word    -> className
//   - 'for' is a reserved word      -> htmlFor
//   - attributes are JS properties  -> onClick, tabIndex, readOnly
//   - a component returns ONE value -> one root element, or a Fragment

<>                            {/* Fragment — groups without a wrapper div */}
  <Header />
  <Main />
</>

// A capital letter means "component"; lowercase means "DOM element".
<button />   // the HTML button
<Button />   // your component

Components and Props

function ProblemCard({ problem, locked = false, onOpen }) {
  return (
    <article onClick={() => onOpen(problem.slug)}>
      <h3>{problem.title}</h3>
      <Difficulty level={problem.difficulty} />
      {locked && <ProBadge />}
    </article>
  )
}

<ProblemCard problem={p} onOpen={open} />          // locked defaults to false
<ProblemCard problem={p} locked onOpen={open} />   // shorthand for locked={true}

// Props are read-only. This is a bug, not a shortcut:
function Bad({ items }) {
  items.sort()                     // mutates the parent's array
  return <List items={items} />
}
function Good({ items }) {
  const sorted = [...items].sort() // copy first
  return <List items={sorted} />
}

Lists and Keys

<ul>
  {problems.map(problem => (
    <ProblemRow key={problem.id} problem={problem} />
  ))}
</ul>

// The key goes on the outermost element of the map, not inside it
{rows.map(r => <Fragment key={r.id}><dt>{r.k}</dt><dd>{r.v}</dd></Fragment>)}

// Keys must be unique among SIBLINGS, not globally.
// Two different lists can both use key={1}.

// Filtering and sorting are just JavaScript
{problems
  .filter(p => p.difficulty === level)
  .sort((a, b) => a.order - b.order)
  .map(p => <ProblemRow key={p.id} problem={p} />)}

// Empty state, always
{problems.length === 0
  ? <EmptyState />
  : problems.map(...)}

Handling Events

<button onClick={handleRun}>Run</button>       // correct — a reference
<button onClick={handleRun()}>Run</button>     // WRONG — calls it now

// Passing an argument needs a wrapper
<button onClick={() => onOpen(problem.slug)}>Open</button>

// Inline is fine. "It creates a new function every render" is true
// and almost never the reason a page is slow — measure before
// contorting the code around it.

// The event object
function handleSubmit(e) {
  e.preventDefault()          // stop the browser navigating
  e.stopPropagation()         // stop it reaching parent handlers
  e.currentTarget.value
}

// Common handlers
onChange onInput onSubmit onKeyDown onFocus onBlur
onMouseEnter onPointerDown onScroll

Rendering and Reconciliation — What Happens on a State Change

// 1. TRIGGER   — initial mount, or a state update in this component
//                 or in one of its ancestors
// 2. RENDER    — React calls your function. It must be PURE: no DOM
//                 writes, no fetches, no mutating outside variables.
//                 The output is a description, not DOM.
// 3. COMMIT    — React diffs against the previous description and
//                 applies only what changed to the real DOM.
// 4. EFFECTS   — after the browser paints, effects run.

// So this component re-renders (function called) but produces the
// same output, and the commit phase does nothing at all:
function Header() { return <h1>AiCanCode</h1> }

// "It re-rendered" is not automatically a problem. The question is
// whether the render did expensive work, or produced DOM changes.

Project Structure and Conventions

src/
  features/
    problems/
      ProblemList.jsx
      ProblemCard.jsx
      ProblemCard.test.jsx      // colocated
      useProblems.js            // the feature's own hook
      api.js                    // the feature's own requests
      types.ts
    auth/
      LoginForm.jsx
      useAuth.js
      AuthProvider.jsx
  components/                   // shared, generic, no feature knowledge
    Button.jsx
    Modal.jsx
    Spinner.jsx
  lib/                          // shared non-UI helpers
    apiClient.js
    formatDate.js
  App.jsx

// The test: to delete "problems", delete one folder.
// With type-based folders you would hunt through four.

// A shared component must not import from features/.
// If it needs to, it is not shared — it belongs to that feature.