docs: Add IntroductionSection component and improve accessibility

[arika0093]

Introduce the IntroductionSection component for query-based DTO generation and enhance accessibility by adding translate attributes to relevant playground components.

Summary by CodeRabbit

• New Features

  • Added interactive step-by-step interface for Query-Based DTO Generation with visual progress tracking, code preview, and dynamic content switching between generated DTO classes and select expressions.

• Updates

  • Updated messaging to reflect auto-generated DTOs from query shape.
  • Removed promotional callout section.

• UI Improvements

  • Enhanced styling and layout refinements across components.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This pull request introduces an interactive step-driven UI component for Query-Based DTO Generation, adds minor styling adjustments to existing components (CSS height and translate attributes), updates content copy in WhyLinqraftSection, and integrates the new component into the Home page layout.

Changes

Cohort / File(s)	Summary
Styling & Attribute Updates playground/Components/Home/CodeBlock.razor, playground/Components/Home/SectionTitle.razor	Added translate="no" attribute; adjusted CSS height constraint from max-h-150 to max-h-120 in CodeBlock.
Content Updates playground/Components/Home/WhyLinqraftSection.razor	Updated bullet text to reflect auto-generated DTOs from query shape; removed UI callout block with bouncing chevron SVG.
New Interactive Component playground/Components/Home/IntroductionSection.razor	Implements multi-step, progress-driven UI with IAsyncDisposable lifecycle. Features include: dynamic step styling, animated progress bar, dual-pane layout (user query + generated code), typewriter animation for code insertion, tab switching (DTO Class / Select Expression), step jumping with conditional animation/consolidation, and full async cancellation/disposal support.
Component Integration playground/Pages/Home.razor	Added IntroductionSection component immediately after HeroSection in the page composition sequence; minor formatting cleanup.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Areas requiring extra attention:

• IntroductionSection.razor: Review typewriter animation logic, step progression and jump-to-step behavior, async state management, and cancellation token handling to ensure timing correctness and no memory leaks on disposal.
• CodeStep nested class: Verify the code consolidation logic and tab-switching implementation (GetCodeForTab method).
• Async lifecycle: Confirm IAsyncDisposable pattern is correctly implemented for timer/cancellation cleanup.

Poem

🐰 Step by step, the query takes shape,
Typewriter whispers code into place,
Progress bars dance, tabs gently switch,
DTO riches from prompts that pitch,
Async cleanup keeps the hutch so tidy! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding the new IntroductionSection component and improving accessibility with translate attributes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/update-playground-pages

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

playground/Components/Home/IntroductionSection.razor (2)

387-397: Consider broader exception handling in timer callback.

The timer's async event handler only catches ObjectDisposedException. If other exceptions occur in TypeNextCharacter or InvokeAsync, they could go unobserved since this is an async void method.

Apply this diff to add comprehensive exception handling:

 typewriterTimer.Elapsed += async (sender, e) =>
 {
     try
     {
         await TypeNextCharacter();
     }
-    catch (ObjectDisposedException) { }
+    catch (Exception ex) when (ex is ObjectDisposedException or TaskCanceledException)
+    {
+        // Expected during disposal
+    }
+    catch (Exception)
+    {
+        // Stop timer on unexpected errors to prevent repeated failures
+        typewriterTimer?.Stop();
+    }
 };

---

342-354: Consider logging when insertion point is not found.

The method silently skips insertion if LastIndexOf(" })") returns -1 or 0. This could lead to incomplete code display without any indication of the problem.

Consider adding defensive logging:

 int insertPosition = displayedCode.LastIndexOf("    })");
-if (insertPosition > 0)
+if (insertPosition > 0)
 {
     displayedCode = displayedCode.Insert(insertPosition, codeToAdd + "\n");
 }
+else
+{
+    // Log or handle the case where insertion point wasn't found
+    // This indicates a mismatch between BaseCode format and expectations
+}

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a25737e and 0fb650a.

📒 Files selected for processing (5)

• playground/Components/Home/CodeBlock.razor (1 hunks)
• playground/Components/Home/IntroductionSection.razor (1 hunks)
• playground/Components/Home/SectionTitle.razor (1 hunks)
• playground/Components/Home/WhyLinqraftSection.razor (1 hunks)
• playground/Pages/Home.razor (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*.cs : Keep helper methods lightweight and focused; helper methods are called frequently during analysis

Applied to files:

• playground/Components/Home/WhyLinqraftSection.razor

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft/DummyExpression.cs : Do not edit `DummyExpression.cs`; it serves only as a marker for the Source Generator

Applied to files:

• playground/Components/Home/WhyLinqraftSection.razor

🔇 Additional comments (8)

playground/Components/Home/CodeBlock.razor (1)

10-10: LGTM! Accessibility and styling improvements.

The addition of translate="no" correctly prevents browser translation of code content, preserving syntax highlighting and formatting. The height adjustment aligns with the new IntroductionSection layout.

playground/Components/Home/WhyLinqraftSection.razor (1)

85-85: LGTM! More accurate description.

The updated wording "auto-generated from query shape" better describes how Linqraft generates DTOs from the query structure, aligning with the new IntroductionSection's focus on query-based generation.

playground/Pages/Home.razor (1)

7-7: LGTM! Logical component placement.

The IntroductionSection is appropriately positioned after the HeroSection to provide an interactive demonstration before the detailed "Why Linqraft?" explanations.

playground/Components/Home/SectionTitle.razor (1)

1-1: Verify that section titles should suppress translation.

Adding translate="no" to section titles prevents browser translation of content like "Why Linqraft?" and "Query-Based DTO Generation." While product names like "Linqraft" shouldn't be translated, the surrounding words typically should be.

Consider whether this aligns with your i18n/accessibility strategy. If the site is intended to be English-only, this is acceptable. Otherwise, you may want to apply translate="no" more selectively (e.g., just to the product name).

playground/Components/Home/IntroductionSection.razor (4)

1-1: LGTM! Proper async disposal implementation.

The component correctly implements IAsyncDisposable and properly cleans up resources (CancellationTokenSource and Timer) in the DisposeAsync method.

Also applies to: 478-490

---

356-408: LGTM! Well-structured step navigation logic.

The method correctly handles both forward (animated) and backward (instant) navigation, with proper cancellation checks and state management. The use of InvokeAsync(StateHasChanged) is appropriate for Blazor.

---

3-88: LGTM! Well-structured interactive UI.

The component's layout is clean and intuitive:

• Step indicators with visual state (completed/current/pending)
• Animated progress bars for typing steps
• Split-pane design showing both input query and generated output
• Tab switching for DTO vs Select Expression views

The use of translate="no" on step indicators (line 24) is appropriate for preserving the UI structure.

---

104-330: LGTM! Well-organized step definitions.

The CodeStep class provides a clean structure for managing step data, and the steps array comprehensively demonstrates Linqraft's features through progressive examples. The data is well-aligned with the README examples.

Also applies to: 492-504

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major

Pass cancellation token to Task.Delay.

Line 425 uses Task.Delay(1000) without a cancellation token. If the component is disposed during this delay, it will continue executing and may attempt operations on disposed resources.

Apply this diff:

-await Task.Delay(1000);
+await Task.Delay(1000, _cts?.Token ?? CancellationToken.None);
 highlightedSection = "";

🤖 Prompt for AI Agents

In playground/Components/Home/IntroductionSection.razor around lines 410 to 443,
the Task.Delay(1000) call should accept the component cancellation token so the
delay is canceled if the component is disposed; replace Task.Delay(1000) with
awaiting Task.Delay(1000, _cts?.Token ?? CancellationToken.None) and after the
await check _cts?.Token.IsCancellationRequested (or return immediately) before
touching highlightedSection/StateHasChanged to avoid operating on disposed
resources.