feat(customized example summaries)

Author: jedwin3210

apps/web/src/App.tsx

@@ -14,7 +14,7 @@ import type { editor as MonacoEditor } from 'monaco-editor';
 const DEFAULT_MARKDOWN = `## How to use this notebook
 
 - **Markdown cell (this cell):** Double-tap or double-click to edit. Use **Shift+Enter** or the **Render** button to see the rendered version and (with Shift+Enter) move to the code cell.
-- **Code cell:** Write Python using \`Table\` and \`make_array\` from the \`datascience\` library. Press **Run** or **Ctrl+Enter** (**Cmd+Enter** on Mac) to execute. The right panel shows step-by-step table operations.
+- **Code cell:** Write Python using the \`datascience\` library. Press **Run** or **Ctrl+Enter** (**Cmd+Enter** on Mac) to execute. The right panel shows step-by-step table operations.
 - **Visualization:** After running, use the arrows to step through operations and **Export** to save as PDF or **Share** to copy a link.`;
 
 const DEFAULT_CODE = `from datascience import *
@@ -407,10 +407,20 @@ function App() {
     })();
   }, [isRunning]);
 
+  // Back to the starter notebook (what you see on first visit)
+  const handleResetNotebook = () => {
+    setCode(DEFAULT_CODE);
+    setMarkdown(DEFAULT_MARKDOWN);
+    setCurrentExample('');
+    setOutput({ stdout: '', stderr: '' });
+    switchMobileView('notebook');
+  };
+
   const handleSelectExample = (example: Example) => {
     console.log('Loading example:', example.title);
     console.log('Example code:', example.code);
     setCode(example.code);
+    setMarkdown(example.markdown);
     setCurrentExample(example.title);
     setOutput({ stdout: '', stderr: '' }); // Clear previous output
     switchMobileView('notebook');
@@ -596,6 +606,7 @@ function App() {
       {showGallery && (
         <ExamplesGallery
           onSelectExample={handleSelectExample}
+          onReset={handleResetNotebook}
           onClose={() => setShowGallery(false)}
         />
       )}

apps/web/src/components/ExamplesGallery.css

@@ -120,6 +120,12 @@
   cursor: pointer;
 }
 
+.example-card-reset {
+  border-style: dashed;
+  border-color: var(--border-strong);
+  background: transparent;
+}
+
 .example-card:hover {
   background: var(--bg-card);
   border-color: var(--text-tertiary);

apps/web/src/components/ExamplesGallery.tsx

@@ -4,10 +4,12 @@ import './ExamplesGallery.css';
 
 interface ExamplesGalleryProps {
   onSelectExample: (example: Example) => void;
+  /** Restore the starter notebook */
+  onReset: () => void;
   onClose: () => void;
 }
 
-export default function ExamplesGallery({ onSelectExample, onClose }: ExamplesGalleryProps) {
+export default function ExamplesGallery({ onSelectExample, onReset, onClose }: ExamplesGalleryProps) {
   const [selectedCategory, setSelectedCategory] = useState<string>('all');
 
   const filteredExamples = selectedCategory === 'all' 
@@ -45,6 +47,27 @@ export default function ExamplesGallery({ onSelectExample, onClose }: ExamplesGa
         </div>
 
         <div className="examples-grid">
+          {selectedCategory === 'all' && (
+            <button
+              type="button"
+              className="example-card example-card-reset"
+              onClick={() => {
+                onReset();
+                onClose();
+              }}
+            >
+              <div className="example-thumbnail">
+                <div className="operation-badges">
+                  <span className="operation-badge">start here</span>
+                </div>
+              </div>
+              <div className="example-info">
+                <h3>Blank notebook</h3>
+                <p>The starter notebook you see on first visit, with instructions and a small table to edit.</p>
+                <div className="example-category">Reset</div>
+              </div>
+            </button>
+          )}
           {filteredExamples.map(example => (
             <button
               type="button"

apps/web/src/index.css

@@ -24,7 +24,7 @@
   -moz-osx-font-smoothing: grayscale;
   font-feature-settings: 'pnum' on, 'lnum' on, 'liga' on;
 
-  /* Jupyter — light (default) */
+  /* Jupyter: light (default) */
   color-scheme: light;
   --bg-app: #faf9f5;
   --bg-header: #faf9f5;
@@ -75,7 +75,7 @@
   background: var(--bg-app);
 }
 
-/* Berkeley — always dark */
+/* Berkeley: always dark */
 [data-theme='berkeley'] {
   color-scheme: dark;
   --bg-app: radial-gradient(circle at top left, rgba(0, 50, 98, 0.92) 0%, rgba(0, 20, 45, 0.96) 55%, #000a1a 100%);

apps/web/src/lib/examples.ts

@@ -9,6 +9,7 @@ export interface Example {
   description: string;
   category: 'basics' | 'filtering' | 'sorting' | 'grouping' | 'joining' | 'transforming';
   operations: string[]; // List of operations demonstrated
+  markdown: string; // Note shown in the markdown cell above the code
   code: string;
   thumbnail?: string;
 }
@@ -18,6 +19,11 @@ export const examples: Example[] = [
     id: 'select-columns',
     title: 'Selecting Columns',
     description: 'Choose specific columns from a table',
+    markdown: `## Selecting columns
+
+\`select\` builds a new table containing only the columns you name, in the order you name them. The original table is left untouched. That is true of every \`Table\` method.
+
+Step through the visualization and notice that the number of rows never changes; only the columns do.`,
     category: 'basics',
     operations: ['select'],
     code: `from datascience import *
@@ -45,6 +51,11 @@ result.show()
     id: 'filter-rows',
     title: 'Filtering Rows',
     description: 'Keep only rows that match a condition',
+    markdown: `## Filtering rows with \`where\`
+
+\`where(column, value)\` keeps only the rows whose value in that column matches. Here we keep the CS majors.
+
+As you step through, watch each row get checked against the condition: kept rows are highlighted, and the ones that don't match are struck through before they disappear from the result.`,
     category: 'filtering',
     operations: ['where'],
     code: `from datascience import *
@@ -71,6 +82,11 @@ cs_students.show()
     id: 'sort-values',
     title: 'Sorting by Values',
     description: 'Order rows by a column',
+    markdown: `## Sorting rows
+
+\`sort(column)\` orders the rows by a column, smallest first. Passing \`descending=True\` flips that, so the highest GPA comes out on top.
+
+Every row survives a sort. Only their order changes. Watch the rows move in the step-through.`,
     category: 'sorting',
     operations: ['sort'],
     code: `from datascience import *
@@ -96,6 +112,11 @@ sorted_students.show()
     id: 'add-column',
     title: 'Adding a Column',
     description: 'Add a new column to the table',
+    markdown: `## Adding a column
+
+\`with_column(label, values)\` returns a copy of the table with one more column. The array of values must have exactly one entry per row, in row order.
+
+Here \`grades\` is an array we build first with \`make_array\`, then attach. Watch the new column appear on the right of the result.`,
     category: 'transforming',
     operations: ['with_column'],
     code: `from datascience import *
@@ -122,6 +143,11 @@ result.show()
     id: 'drop-column',
     title: 'Dropping Columns',
     description: 'Remove columns from a table',
+    markdown: `## Dropping columns
+
+\`drop\` is the mirror image of \`select\`: you name the columns you want to get rid of, and everything else stays.
+
+Use it when a table has many columns and it is easier to say what you don't need.`,
     category: 'basics',
     operations: ['drop'],
     code: `from datascience import *
@@ -149,6 +175,11 @@ result.show()
     id: 'group-aggregate',
     title: 'Grouping and Aggregating',
     description: 'Group rows and compute statistics',
+    markdown: `## Grouping and aggregating
+
+\`group(column, function)\` collects the rows that share a value in the column, then applies the function to each group's values. With \`sum\`, every product ends up with the total of its amounts.
+
+Step through it: first the rows are gathered into groups, then the values in each group are collapsed into one number. Notice the new column is named \`Amount sum\`.`,
     category: 'grouping',
     operations: ['group'],
     code: `from datascience import *
@@ -175,6 +206,11 @@ totals.show()
     id: 'join-tables',
     title: 'Joining Tables',
     description: 'Combine two tables on a common column',
+    markdown: `## Joining two tables
+
+\`join(column, other_table)\` matches rows from two tables that share a value in the named column and lines them up side by side.
+
+Here both tables have an \`ID\` column. Watch the second table appear under the first, with matching keys highlighted as each row is paired up.`,
     category: 'joining',
     operations: ['join'],
     code: `from datascience import *
@@ -210,6 +246,11 @@ result.show()
     id: 'chain-operations',
     title: 'Chaining Operations',
     description: 'Combine multiple operations in sequence',
+    markdown: `## Chaining operations
+
+Because every \`Table\` method returns a new table, you can call another method on the result right away. Wrapping the expression in parentheses lets you put each step on its own line.
+
+Read it top to bottom: keep the CS majors, keep only name and GPA, then sort. The visualization shows one step per method call.`,
     category: 'basics',
     operations: ['select', 'where', 'sort'],
     code: `from datascience import *
@@ -240,6 +281,11 @@ result.show()
     id: 'multiple-filters',
     title: 'Multiple Filters',
     description: 'Apply multiple where conditions',
+    markdown: `## Filtering twice
+
+A second \`where\` on the result of the first narrows things down further. \`are.above(3.5)\` is a *predicate*, a reusable condition, from the \`are\` collection.
+
+Compare the two filter steps: the first checks the Major column, the second checks GPA against a threshold.`,
     category: 'filtering',
     operations: ['where'],
     code: `from datascience import *
@@ -274,6 +320,11 @@ high_gpa.show()
     id: 'pivot-table',
     title: 'Pivot Tables',
     description: 'Reshape data with pivot operations',
+    markdown: `## Pivoting
+
+\`pivot(columns, rows, values, function)\` turns one column's values into column headers and another's into row labels, then fills each cell by aggregating the \`values\` column.
+
+Here every Product becomes a column and every Region a row, and each cell is the sum of Sales for that pair. Step through to see the source rows feed each cell.`,
     category: 'transforming',
     operations: ['pivot'],
     code: `from datascience import *
@@ -300,6 +351,11 @@ pivoted.show()
     id: 'group-multiple',
     title: 'Group with Multiple Aggregates',
     description: 'Group by column and compute multiple statistics',
+    markdown: `## Different aggregates on the same groups
+
+The function you pass to \`group\` decides what each group collapses to. \`np.mean\` gives the average score per major; \`max\` gives the highest.
+
+The groups are identical in both calls. Only the number in the second column changes, and so does its name: \`Score mean\` versus \`Score max\`.`,
     category: 'grouping',
     operations: ['group'],
     code: `from datascience import *
@@ -332,6 +388,11 @@ max_scores.show()
     id: 'join-multiple-keys',
     title: 'Joining on Multiple Keys',
     description: 'Join tables with multiple matching columns',
+    markdown: `## Joining on an ID
+
+\`StudentID\` is the key that links a student's record to their enrollment. \`join\` pairs each row in \`students\` with the row in \`enrollment\` that has the same ID.
+
+Watch the keys get matched one at a time, and notice the joined table keeps the columns from both.`,
     category: 'joining',
     operations: ['join'],
     code: `from datascience import *
@@ -368,6 +429,11 @@ result.show()
     id: 'complex-workflow',
     title: 'Complex Workflow',
     description: 'Combine multiple advanced operations',
+    markdown: `## A full pipeline
+
+This is the shape of most real analyses: filter down to the rows you care about, select the useful columns, group to summarise, and sort to rank.
+
+Watch how the table changes character at each step, from individual transactions to one row per product. The sort uses \`Amount sum\`, the column that \`group\` created.`,
     category: 'basics',
     operations: ['select', 'where', 'group', 'sort', 'join'],
     code: `from datascience import *
@@ -400,6 +466,11 @@ result.show()
     id: 'take-sample',
     title: 'Taking Sample Rows',
     description: 'Select a specific number of rows from a table',
+    markdown: `## Taking rows by position
+
+\`take(n)\` returns the first \`n\` rows. You can also pass a specific row number, or a range of them, using \`take(np.arange(start, stop))\`.
+
+Row positions start at 0. Watch the first three rows get picked out and the rest fall away.`,
     category: 'basics',
     operations: ['take'],
     code: `from datascience import *
@@ -426,6 +497,11 @@ sample.show()
     id: 'pivot-complex',
     title: 'Complex Pivot Operation',
     description: 'Reshape data with multiple dimensions',
+    markdown: `## Pivoting scores
+
+Each student took each subject once, so the pivot has one row per student and one column per subject, and each cell holds that student's score.
+
+Step through and check that every (student, subject) pair from the original table lands in exactly one cell.`,
     category: 'transforming',
     operations: ['pivot'],
     code: `from datascience import *
@@ -452,6 +528,11 @@ pivoted.show()
     id: 'group-with-aggregate',
     title: 'Group with Custom Aggregate',
     description: 'Group data and apply custom aggregation functions',
+    markdown: `## Total versus average
+
+Grouping by Region with \`sum\` gives each region's total; grouping with \`np.mean\` gives its average. The groups are the same, the summary differs.
+
+Notice the group step happens first in both calls, and the aggregation happens after.`,
     category: 'grouping',
     operations: ['group'],
     code: `from datascience import *
@@ -484,6 +565,11 @@ avg_by_region.show()
     id: 'multi-step-analysis',
     title: 'Multi-Step Data Analysis',
     description: 'Complete workflow: filter, group, sort, and select',
+    markdown: `## Filter, group, sort, select
+
+A four-step analysis, one method at a time. Keep employees with at least three years (\`are.above_or_equal_to\`), average each department's scores, rank the departments, then keep just the two columns worth reporting.
+
+Watch the \`Years\` column disappear after the group step: once rows are collapsed into groups, only the aggregated columns remain.`,
     category: 'basics',
     operations: ['where', 'group', 'sort', 'select'],
     code: `from datascience import *

apps/web/src/lib/tracer.py

@@ -264,7 +264,7 @@ def _sub_steps_group(table, args, kwargs, input_state, output_state):
     })
 
     steps.append({
-        "message": f"Find the unique values in '{label}' — each one becomes exactly one row of the result.",
+        "message": f"Find the unique values in '{label}'. Each one becomes exactly one row of the result.",
         "detail": f"Unique values (sorted): {_fmt_list(uniq)}",
         "input_highlights": {"columns": [label]},
         "output_state": _make_state(out_cols, []),
@@ -501,13 +501,13 @@ def _sub_steps_sort(table, args, kwargs, input_state, output_state):
         if descending:
             order = order[::-1]
         steps.append({
-            "message": "Rows keep all their values — only their order changes.",
+            "message": "Rows keep all their values. Only their order changes.",
             "detail": f"New order of original row positions: {_fmt_list([int(i) + 1 for i in order])}",
             "output_highlights": {"columns": [label]},
         })
     except Exception:
         steps.append({
-            "message": "Rows keep all their values — only their order changes.",
+            "message": "Rows keep all their values. Only their order changes.",
             "output_highlights": {"columns": [label]},
         })
     return steps
@@ -547,7 +547,7 @@ def _sub_steps_join(table, args, kwargs, input_state, output_state):
             "output_state": _make_state(output_state["columns"], []),
         },
         {
-            "message": "Find the key values that appear in BOTH tables — only those rows will be joined.",
+            "message": "Find the key values that appear in BOTH tables. Only those rows will be joined.",
             "detail": f"Keys found in both tables: {_fmt_list(shared)}",
             "input_highlights": {"rows": left_match, "columns": [label]},
             "aux_table": {"label": "Second table", "state": aux_state,