chore(docs): updates (#1683)

Author: brendt

docs/0-getting-started/01-introduction.md

@@ -96,6 +96,10 @@ final class ConsoleCommandDiscovery implements Discovery
 
 Discovery makes Tempest truly understand your codebase so that you don't have to explain the framework how to use it. Of course, discovery is heavily optimized for local development and entirely cached in production, so there's no performance overhead. Even better: discovery isn't just a core framework feature, you're encouraged to write your own project-specific discovery classes wherever they make sense. That's the Tempest way.
 
+:::info
+Read the [getting started with discovery](/blog/discovery-explained) guide if you are new to Tempest.
+:::
+
 Besides Discovery, Tempest is designed to be extensible. You'll find that any part of the framework can be replaced and hooked into by implementing an interface and plugging it into the container. No fighting the framework, Tempest gets out of your way.
 
 ```php

docs/1-essentials/01-routing.md

@@ -336,44 +336,19 @@ Whenever a validation error occurs, Tempest will redirect back to the page the r
 - As a JSON encoded string in the `{txt}X-Validation` header
 - Within the session with the `Session::VALIDATION_ERRORS` key
 
-The JSON encoded header is available for when you're building APIs with Tempest. The session errors are available for when you're building web pages. In the case of the latter, you need a way to actually show the errors on a web page. Tempest's recommended way to do so is by creating a custom [view component](/docs/essentials/views#view-components):
-
-```html app/x-error.view.php
-<?php
-use Tempest\Http\Session\Session;
-use Tempest\Validation\Validator;
-use function Tempest\get;
-
-/** @var Session $session */
-$session = get(Session::class);
-
-/** @var Validator $validator */
-$validator = get(Validator::class);
-
-$errors = $session->getErrorsFor($name ?? '');
-
-?><ul :if="$errors !== []" :class="$class ?? ''">
-    <li :foreach="$errors as $error">
-        {{ $validator->getErrorMessage($error) }}
-    </li>
-</ul>
-```
-
-This view component will be discovered and can then be used to display validation errors likes so:
+The JSON encoded header is available for when you're building APIs with Tempest. The session errors are available for when you're building web pages. For web pages, you also need a way to show the errors when they occur; Tempest comes with some built-in view components to help you with that.
 
 ```html
-<form action="/register" method="post">
-    <label for="name">Name</label>
-    <input type="text" name="name" id="name" autofocus class="border"/>
-    <x-error name="name" class="text-red-400 …" />
+<x-form :action="uri(StorePostController::class)">
+    <x-input name="name" />
+    
+    <x-input type="email" name="email" />
 
-    <!-- … -->
-</form>
+    <x-submit />
+</x-form>
 ```
 
-:::info
-Currently, Tempest doesn't include built-in view components to handle form validation. That's because we don't have a strategy yet for dealing with different frontend frameworks. We rather give control to the user to build their own form components for maximum flexibility. This is likely to change in the future, but for now you'll have to make your own `x-error` component.
-:::
+`{html}<x-form>` is a view component that will automatically include the CSRF token, as well as default to sending `POST` requests. `{html}<x-input>` is a view component that renders a label, input field, and validation errors all at once. In practice, you'll likely want to make changes to these built-in view components. That's why you can run `./tempest install view-components` and select the components you want to pull into your project. You can [read more about installing view components here](/2.x/essentials/views#built-in-components).
 
 ## Route middleware
 

docs/1-essentials/02-views.md

@@ -622,6 +622,23 @@ Tempest views are always compiled to plain PHP code before being rendered. Durin
 
 During deployments, that cache must be cleared in order to not serve outdated views to users. You may do that by running `tempest view:clear` on every deploy.
 
+## Separate view directories
+
+View files can live in any directory that is discoverable by Tempest. That means: a directory with a PSR-4 namespace associated with it. If you want your view files to live outside of `src` or `app`, you can add a namespace for it in composer.json:
+
+```json composer.json
+"autoload": {
+    "psr-4": {
+        "App\\": "src/",
+        "Views\\": "views/"
+    },
+}
+```
+
+Don't forget to run `composer up` after making changes to your composer.json file.
+
+Note that view files themselves don't need a namespace; this namespace is only here to tell Tempest that `views/` is a directory it should scan. If you want to add a class in the `Views` namespace (like, for example, a [custom view object](/2.x/essentials/views#using-dedicated-view-objects)), then that is possible as well. 
+
 ## Using other engines
 
 While Tempest View is simple to use, it currently lacks tooling support from editors and IDEs. You may also simply prefer other templating engines. For these reasons, you may use any other engine of your choice.

docs/2-features/15-datetime.md

@@ -10,6 +10,10 @@ PHP provides multiple date and time implementations. There is [`DateTime`](https
 
 Tempest provides an alternative to [`DateTimeInterface`](https://www.php.net/manual/en/class.datetimeinterface.php), partially based on [`IntlCalendar`](https://www.php.net/manual/en/class.intlcalendar.php). This implementation provides a better API with a more consistent interface. It was initially created by {x:azjezz} for the [PSL](https://github.com/azjezz/psl), and was ported to Tempest so it could be deeply integrated.
 
+:::info
+You're not required to use Tempest's DateTime implementation, and may as well use PHP's native datetime, Carbon, or any other. If you rely on third-party libraries like Carbon, you should read about [global casters and serializers](/2.x/features/mapper#registering-casters-and-serializers-globally) as well to ensure model support.  
+:::
+
 ## Creating date instances
 
 The {`Tempest\DateTime\DateTime`} class provides a `DateTime::parse()` method to create a date from a string, a timestamp, or another datetime instance. This is the most flexible way to create a date instance.

docs/4-internals/02-discovery.md

@@ -3,6 +3,10 @@ title: Discovery
 description: "Learn how Tempest automatically locates controller actions, event handlers, console commands, and other components of your application."
 ---
 
+:::info
+Read the [getting started with discovery](/blog/discovery-explained) guide if you are new to Tempest. 
+:::
+
 ## Overview
 
 Tempest introduces a unique approach to bootstrapping an application. Instead of requiring manual registration of project code and packages, Tempest automatically scans the codebase and detects the components that should be loaded. This process is called **discovery**.