Onboarding tutorials with Task Reference panel#2250
Open
7h3kk1d wants to merge 28 commits into
Open
Conversation
Copy 22 language-feature tutorials (the Tu_* set plus Ta_StringMean renamed to Tu_StringMean) from the tables-study user-study branch. Drop the table, rich-probes, and live-typing tutorials since those features aren't on dev. Labeled-tuple tutorials are kept since labeled tuples are on dev. Tutorial.spec gains task_reference and setting_overrides fields plus with_title/with_prompt/with_task_reference/with_rich_probes builders. The instructor-mode editability UI from tables-study is intentionally omitted. Add a TaskReference sidebar panel that renders TaskRefDocs markdown for the active tutorial; the tab only appears when a tutorial has a non- empty task_reference. TaskRefDocs is filtered to the entries the kept tutorials actually reference. Tables-study Zipper serializations include a refractors literal whose shape no longer matches dev's Refractors.t; replaced those literals with Haz3lcore.Refractors.init. Parser.to_zipper calls updated for dev's required ~root parameter. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mk_translation in ExplainThis only handled paragraphs and basic unordered lists, so fenced ```hazel / hazelnoeval / hazelnostatics blocks fell through to nothing and tutorial prompts looked plain. Add Code_block, Heading, and Strong handling, ordered-list and tight-list support, and a memoized parser so each fenced hazel block renders as a locked CellEditor with the appropriate statics/dynamics settings - matching how tables-study rendered tutorial prompts and the task-reference sidebar. Also add a .task-reference-panel CSS rule so the sidebar gets the same scroll/padding/flex layout it had on tables-study. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Also move the task-reference tab to the front of the persistent tab strip when present, since it's the most relevant panel for tutorial users. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
If the active panel is TaskReference but the current editor has no task_reference (e.g. user switched to Scratch), render LanguageDocumentation instead of an empty "No task reference available" panel whose tab no longer exists. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Headings rendered by mk_translation were inheriting the browser-default gray. Match the brown tone (--BR4) used by other Hazel headings like .slide h1 and .hsod-body h1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Browser-default h1 (2em) was rendering bigger than the .title-text header (1.5rem), making the tutorial title look subordinate to its own prompt headings. Scale h1-h6 inside .prompt-content and .task-reference-panel below 1.5rem so the title stays largest. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Matches the sidebar panel name. Untouched: ProbeSidebar's "Quick Reference" section, BasicReference docs, and the Benchmark sample, which are unrelated to the tutorial task-reference feature. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The 'Task Reference' header is no longer baked into TaskRefDocs.compose or hand-written tutorial task_reference strings. The sidebar now wraps the markdown body with a sticky styled header, separated from the scrollable body region. Removed the now-redundant '## Task Reference' prefix from compose/prepend and from the six hand-written tutorial strings. Polish: panel uses a header bar with --T2 background and brown title, section headings (h3/h4) get a subtle bottom border, inline `code` gets a chip background, paragraphs and lists get tighter spacing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drop the colored header bar and brown-on-cream contrast block. Title and section headings (###) are now typographic: uppercase, bold, ~1em, in --ui-header-text (--BR3), matching how #probe-sidebar .main-title and .header are styled. Body inherits panel background; spacing comes from gap rather than block boundaries. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Each ### heading becomes a <details> card outlined in BR1 with rounded corners (Probearium .panel style), default open. The summary serves as the click target with an animated rotating chevron and uppercase brown-on-cream title styling. No JS state needed - native HTML disclosure. split_task_reference_sections walks the markdown body line-by-line and groups blocks under each ### heading; preamble content (before any heading) renders unwrapped above the cards. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CellEditor.View laid out wider than the sidebar panel and bled past the section's right edge. overflow:hidden + min-width:0 on the section and section-body keeps the editor visually clipped to the card. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When a section is open, its title drops the bold uppercase treatment in favor of --BR2, font-weight 400, 0.85em - mirroring how .panel .title renders in the Probearium. Collapsed sections keep the bolder uppercase header so they read as clickable section markers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Titles
- "Multi-argument functions" -> "Multi-Argument Functions"
- "Labeled tuple projection" -> "Labeled Tuple Projection"
- "Labeled tuple extension" -> "Labeled Tuple Extension"
- "Labeled Tuple List Conversions " -> trim trailing space
Display hints
- Standardize: drop all trailing periods (most already had none).
- Drop trailing space on Tu_FunctionMultiArg hint.
Content bugs
- Tu_Pipelines example used a list mixing Int and Float values
([-1, 0, 0.5, 1]) which is invalid Hazel; replaced with [-1, 0, 1, 2].
- Tu_TupleList described from_lvs as "the inverse of from_lvs" - it's
the inverse of `to_lvs`. Also dropped a stray period after "the
function:.".
- Tu_LabeledTuples task_reference contained the FloatingPoint
reference text (wrong content). Replaced with TaskRefDocs.tuple_projection.
Prompt clarity
- Tu_LetBindings: "20% of the meal" / "20% of the price" inconsistency
cleaned up; comma splice fixed.
- Tu_LabelOmission: missing periods, awkward "via... using" phrasing
tightened.
- Tu_Partial: bullet list mixed tense ("if n is negative returns 0"
vs "Otherwise return n") - made parallel.
- Tu_TupleExtension: dropped redundant H1 (title already shown in
cell), bullet capitalization made consistent.
- Tu_TylrParser: numbered steps now end with periods; "then... then...
then" reduced.
- Tu_Holes: typo "displayed as hexagon" -> "hexagons"; mention "Task
Reference sidebar" by name.
- Tu_FunctionMultiArg: "2 arguments" -> "two arguments"; tightened.
- Tu_Projection, Tu_StringMean, Tu_CaseExpressions, Tu_TupleList,
Tu_FloatingPointArithmetic, Tu_LabeledTuples: minor punctuation,
comma, em-dash, and structural cleanup.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add Omd.Thematic_break handling in mk_translation so '---' in tutorial prompts and task references renders as <hr>. Style hr inside .task-reference-body with border-top: 0.6px solid var(--BR1) and modest vertical margin - mirrors the Probearium .qr-divider / .legend-divider pattern. Insert '---' separators in TaskRefDocs entries that have a clear two-part structure: type signature + example (map, fold_left, filter, zip, find, filteri, to_lvs, from_lvs) and the case expression's two distinct examples. Authors can drop '---' anywhere in tutorial markdown to get the same divider. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Was a flat blob with H1 + two unlabeled code blocks; didn't render as a collapsible section or pick up the new divider treatment. Restructure as a ### Label Omission section with explanatory blurbs and a '---' between the single-label and multi-label examples. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Was four overlapping variants (type_conversions_full, type_conversions_string_float, type_conversions_float_of_int, type_conversions_float_int) with inconsistent prose, formatting, and example placement. Replace with a single TaskRefDocs.type_conversions entry that lists all four primitive conversions as a uniform type-signature list, then a '---' divider, then one example per conversion. Tu_StringMean and Tu_Pipelines updated to reference the new name. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…sions Match the map/filter pattern: hazelnostatics blocks hold the type signatures, then a '---' divider, then per-function example cells. Replaces the call-shape `string_sub(str, start, length)` placeholder. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## dev #2250 +/- ##
==========================================
+ Coverage 50.91% 50.93% +0.01%
==========================================
Files 300 301 +1
Lines 39867 39888 +21
==========================================
+ Hits 20300 20316 +16
- Misses 19567 19572 +5
🚀 New features to boost your workflow:
|
The setting_overrides record on Tutorial.spec was plumbed through the data model but never consumed — no code reads rich_probes, display_tables, or read_only. Drop the field, helpers, and per-tutorial assignments. Also drop the unused TaskRefDocs.prepend helper. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the if/else-if ladder on the trimmed language tag with a single switch, and share one fallback for unknown langs and unparseable code instead of duplicating the <pre><code> construction in two arms. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the line-based "### " text splitter with a pass over the parsed Omd doc, splitting on Heading(_, 3, _). Expose mk_translation_doc and inline_to_string from ExplainThis so the sidebar can parse the markdown once and feed each section's blocks straight to the renderer, instead of re-serializing and re-parsing per section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Also add a leading comment in TaskRefDocs documenting the ### Title convention that split_task_reference_sections relies on, and a unit test covering empty/preamble/single/multi/H2 cases. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The test pulled Web.Sidebar into haz3ltest, which transitively linked WorkerClient.re's top-level initWorker() — failing under Node with "worker is not a constructor". Move split_task_reference_sections (and the small inline_to_string helper) into TaskReferenceSplit.re so the test can import a module whose only dep is Omd. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ports the Hazel onboarding tutorial set from the
tables-studybranch and adds the supporting UI for running them in tutorial mode.The tutorials walk new users through Hazel's core language features — arithmetic, let bindings, functions, lists, tuples, labeled tuples, case expressions, pipelines, projection, holes, probes, and more — as a sequence of guided exercises.
Alongside the content, this branch adds a Task Reference panel: a sidebar that surfaces per-tutorial reference material (renamed from "Quick Reference"). It opens by default in tutorial mode, is collapsible, clips embedded editors that overflow, and is restyled to match the Probearium aesthetic (panel title, headings, dividers, brown heading color, capped heading sizes). When the user leaves tutorial mode the sidebar falls back to LanguageDocumentation.
Markdown rendering in tutorial prompts also gets a pass: fenced
hazelcode blocks, headings, and thematic breaks (rendered as Probearium-style dividers) are now supported, and a copy-edit pass cleaned up titles, prompts, and hints across the tutorial set.Test plan
make devbuilds cleanly🤖 Generated with Claude Code