feat: Implement Quick Tutorial flow with keyboard-based chapter filtering

[prince-0408]

Closes #649

Summary

The "Quick tutorial" button in InstallationVC had a blank action — clicking it did nothing. This PR implements the full interactive tutorial flow as designed in Figma, allowing users to learn Scribe keyboard features through hands-on practice with interactive "Try it here" text fields.

What's Implemented

Core Features

Entry screen (TutorialView):

• Tip card with lightbulb icon and OK button
• Description card: "This quick tutorial will show you how to use Scribe to support writing in your target language."
• List of 4 tutorial chapters with chevron navigation
• "Start full tutorial" button for sequential walkthrough

Chapter screens (TutorialChapterView):

• Multi-step support (Noun annotation has 2 steps: Vater → Mutter)
• Interactive text fields for hands-on practice — users actually type and get feedback
• Real-time validation with correct/incorrect feedback
• Language note with globe icon
• Sequential navigation in full tutorial mode

Keyboard detection (TutorialKeyboardDetector):

• Reads installed Scribe keyboards from UserDefaults
• Hides Noun annotation chapter if only English keyboard is installed
• Shows all chapters if no keyboards installed (user may install later)

Wrong keyboard warning:

• Detects when non-Scribe keyboard is active on .onAppear
• Shows "Non-Scribe keyboard" screen with instruction to press 🌐

UI/UX Details

Navigation bar behavior (matches Figma):

• Idle state: < Quick tutorial (leading only, no xmark)
• Feedback state: bare < (leading) + × (trailing)
• Wrong keyboard: bare < (leading) + × (trailing)

Feedback messages:

• ✅ Correct: "Great! Press Next to continue." (green)
• ❌ Incorrect: "Not quite! Try writing [word]." (red)

Other details:

• Back button style matches existing app views (pill/capsule background)
• Last chapter shows "Finish tutorial" instead of "Next"
• Chapters 2–4 (Word translation, Verb conjugation, Noun plurals) have no text field — instruction-only

Logic Rules Implemented

Noun Annotation Chapter Visibility

Rule: Hide the Noun annotation chapter if only English keyboard is installed, since English nouns don't have grammatical gender.

Implementation:

// TutorialKeyboardDetector.swift
static func availableChapters() -> [TutorialChapter] {
    if hasNounAnnotationKeyboard() {
        return TutorialChapter.allCases
    } else {
        return TutorialChapter.allCases.filter { $0 != .nounAnnotation }
    }
}

Languages with noun-gender annotations:
German, Spanish, French, Portuguese, Russian, Italian, Swedish, Norwegian, Danish, Hebrew, Indonesian

Edge cases handled:

• No keyboards installed → show all chapters (user may install later)
• Only English installed → hide Noun annotation
• English + any gender-language → show all chapters

Wrong Keyboard Detection

Rule: Show warning screen if user opens tutorial with a non-Scribe keyboard active.

Implementation:

• Checks on .onAppear of chapter view
• Compares installed keyboards against Scribe bundle identifier prefix
• Shows "Press the 🌐 button to select a Scribe keyboard" message

Files Changed

New Files (7)

• Scribe/Tutorial/TutorialView.swift — Entry screen
• Scribe/Tutorial/TutorialChapterView.swift — Chapter display with multi-step support
• Scribe/Tutorial/TutorialChapter.swift — Chapter enum (4 chapters)
• Scribe/Tutorial/TutorialChapterContent.swift — Step definitions and instructions
• Scribe/Tutorial/TutorialStep.swift — Step model
• Scribe/Tutorial/TutorialTipCard.swift — Tip card component
• Scribe/Tutorial/TutorialKeyboardDetector.swift — Keyboard detection logic

Modified Files (3)

• Scribe/InstallationTab/InstallationVC.swift — Wired "Quick tutorial" button to present TutorialView
• Scribe.xcodeproj/project.pbxproj — Added new Tutorial files to Xcode project
• Scribe/i18n submodule — Updated with new localization keys in Localizable.xcstrings

Screenshots

Add screenshots of:

• Entry screen with tip card, description, chapter list
• Noun annotation step 1 (Vater) with correct feedback
• Noun annotation step 2 (Mutter) with incorrect feedback
• Word translation chapter (instruction-only, no text field)
• Wrong keyboard warning screen

Questions for Review

1. Keyboard detection method: Currently using UserDefaults.standard.dictionaryRepresentation()["AppleKeyboards"] — is this the correct approach or should we use a different API?

2. Additional logic rules needed? Are there other scenarios where chapters should be hidden/shown based on:

   • Specific keyboard combinations?
   • User settings/preferences?
   • First-time vs returning users?

3. Localization: All strings use NSLocalizedString with English defaults. Should we pre-translate any languages or wait for Weblate?

4. Accessibility: Should we add VoiceOver labels/hints for the interactive text fields and feedback states?

Testing Checklist

• Entry screen displays correctly with all cards and chapter list
• Tapping individual chapter opens that chapter only
• "Start full tutorial" navigates through all chapters sequentially
• Noun annotation step 1 (Vater) validates correctly
• Noun annotation step 2 (Mutter) validates correctly
• Incorrect input shows red feedback message
• Correct input shows green feedback and enables Next
• Chapters 2-4 have no text field (no expected input)
• Last chapter shows "Finish tutorial" button
• English-only keyboard hides Noun annotation chapter
• German/Spanish/etc keyboard shows all 4 chapters
• Wrong keyboard warning appears when non-Scribe keyboard active
• Back button behavior matches Figma (text visibility changes with feedback)
• Navigation dismisses correctly from any screen

Related

• Issue: Implement Quick Tutorial Flow with Noun Annotation Logic Rules #649
• Figma design: scribe_public_designs

Screenshots

[github-actions]

Thank you for the pull request! 💙🩵

The Scribe-iOS team will do our best to address your contribution as soon as we can. The following are some important points:

• Those interested in developing their skills and expanding their role in the community should read the mentorship and growth section of the contribution guide
• If you're not already a member of our public Matrix community, please consider joining!
  • We'd suggest that you use the Element client as well as Element X for a mobile app
  • Join the General and iOS rooms once you're in
• Also consider attending our bi-weekly Saturday developer syncs!
  • Details are shared in the General room on Matrix each Wednesday before the sync
  • It would be great to meet you 😊

Note

Scribe uses Conventional Comments in reviews to make sure that communication is as clear as possible.

[github-actions]

Maintainer Checklist

The following is a checklist for maintainers to make sure this process goes as well as possible. Feel free to address the points below yourself in further commits if you realize that actions are needed :)

• Tests for changes have been written and the CI unit test, linting and formatting workflows within the PR checks do not indicate new errors in the files changed

• The CHANGELOG has been updated with a description of the changes for the upcoming release and the corresponding issue (if necessary)