New features

Author: pascalbaljet

form-submit.md

@@ -13,4 +13,12 @@ You may also use a slot:
     <svg>...</svg>
     <span>Send now</span>
 </x-splade-submit>
+```
+
+In addition to providing a custom template with a slot, you may change the styling of the default submit button with the `danger` or `secondary` attributes:
+
+```blade
+<x-splade-submit danger label="Remove account" />
+
+<x-splade-submit secondary label="Save for later" />
 ```

splade-vs-livewire.md

@@ -14,7 +14,7 @@ To summarize:
 
 ## Components
 
-Livewire works by building **Livewire-specific** Components. It has its own syntax in Blade templates with `wire:*` attributes and directives. Splade works with Laravel's *native* [Blade Components](https://laravel.com/docs/9.x/blade) and Vue Components. Though some features of Splade require a single Middleware (like the SPA-navigation features), it doesn't need a custom compiler or engine to work.
+Livewire works by building **Livewire-specific** Components. It has its own syntax in Blade templates with `wire:*` attributes and directives. Splade works with Laravel's *native* [Blade Components](https://laravel.com/docs/9.x/blade) and Vue Components. Though some features of Splade require a single Middleware (like the SPA-navigation features), you don't need to create *Splade-specific* components, it's all just Blade and Vue.
 
 To summarize:
 * Splade doesn't need the creation of *special* components as it uses native Laravel and Vue implementations to achieve reactivity.

x-data.md

@@ -72,3 +72,23 @@ The remembered state will be lost whenever the user fully refreshes the app. You
     <button @click.prevent="data.accepted = true">Accept</button>
 </x-splade-data>
 ```
+
+## Global Store
+
+Sometimes you want to use a set of reactive data through the template or layout. Instead of wrapping everything inside the data component, you may also define a store and use it at other places in your template.
+
+```blade
+<x-splade-data store="navigation" default="{ opened: false }" />
+
+<!-- other elements... -->
+
+<button @click.prevent="navigation.opened = true">
+    Open Navigation
+</button>
+
+<nav v-show="navigation.opened">
+    ...
+</nav>
+```
+
+You must pass a key to the `store` attribute and avoid generic naming. For example, don't use keys like *data*, *form*, and *toggle* as they might interfere with other scoped Vue components.

x-defer.md

@@ -12,14 +12,28 @@ The **Defer Component** allows you to load data asynchronously. The component ex
 
 ## Request body
 
-By default, the component performs a `GET` request with an `application/json` accept header. You may change this with the `method` and `accept-header` attributes. In case you need to post data, you may use the `request` attribute:
+By default, the component performs a `GET` request with an `application/json` accept header. You may change this with the `method` and `accept-header` attributes. In case you need to post data, you may use the `request` attribute. Just like the [Data component](/x-data.md), it allows you to pass a PHP value *or* a JavaScript object. The value passed to the `request` attribute will be parsed by Vue, not by PHP.
 
 ```blade
 <x-splade-defer method="POST" url="/post/increase" request="{ post_id: 1 }">
     ...
 </x-splade-defer>
 ```
 
+If you want to parse the value by PHP, you may use the `:request` attribute (note the colon).
+
+```blade
+<x-splade-defer method="POST" url="/post/increase" :request="['post_id' => 1]">
+```
+
+You can do the same for adding headers:
+
+```blade
+<x-splade-defer method="POST" url="/post/increase" headers="{ 'In-Background': 1 }">
+
+<x-splade-defer method="POST" url="/post/increase" :headers="['In-Background' => 1]">
+```
+
 ## Poll
 
 You may also use this component to poll for new data. With the `poll` attribute, you can specify the interval in milliseconds.
@@ -60,6 +74,25 @@ The component can watch a passed value for changes using the `watch-value` attri
 
 If you want to watch all form data, you may pass `form.$all` to the `watch-value` attribute.
 
+## Event
+
+The component emits `success` and `error` events, allowing you to interact with the response data within your template. For example, you may set a form value on a successful request. Note that the `url` attribute supports *Template literals*, making it perfect for generating dynamic URLs:
+
+```blade
+<x-splade-form>
+    <x-splade-input name="zip" label="ZIP code" />
+    <x-splade-input name="city" label="City" />
+
+    <x-splade-defer
+        url="`https://example-city-api.com/${form.zip}/json/`"
+        watch-value="form.zip"
+        watch-debounce="100"
+        manual
+        @success="(response) => form.city = response.city"
+    />
+</x-splade-form>
+```
+
 ## Async templates and Rehydration
 
 If you want to load sections of your template asynchronously, check out the [Lazy Loading](/lazy-loading.md) section. There's also a [Rehydrate Component](/x-rehydrate.md) to reload a section of your Blade template.

x-form.md

@@ -105,6 +105,8 @@ In addition, you may customize the confirmation dialog:
 >
 ```
 
+Instead of the `confirm` attribute, you may also use the `confirm-danger` attribute to render a red confirmation button.
+
 ### Password Confirmation
 
 It's even possible to require the user to confirm their password within the confirmation dialog. First, you must register a supporting route using the `spladePasswordConfirmation()` method on the `Route` facade. As of version 1.2.2, the automatic installer does this for you. If you need to register the route manually, make sure it uses the `web` Middleware, for example, in `web.php`:
@@ -125,6 +127,12 @@ Only when the password is correct it submits the form. Splade will add the enter
 <x-splade-form confirm require-password="password_confirmation">
 ```
 
+To prevent users from re-entering their password over and over, you may use the `require-password-once` attribute. Once the user has successfully entered their password, it won't be asked again until the number of seconds (defined with the `auth.password_timeout` config key) has elapsed:
+
+```blade
+<x-splade-form confirm require-password-once>
+```
+
 ## File uploads
 
 You may use the input event to bind the selected file to your form data:
@@ -139,6 +147,23 @@ You may use the input event to bind the selected file to your form data:
 
 The dedicated [File Component](/form-file.md) provides a cleaner solution, and has support for selecting multiple files as well as displaying the filename of the selected file.
 
+
+## State
+
+There are several props that you can use to show the state of the form:
+
+```blade
+<x-splade-form>
+    <p v-if="form.processing">Submitting the data...</p>
+</x-splade-form>
+
+<x-splade-form stay>
+    <p v-if="form.wasSuccessful">Successfully submitted!</p>
+
+    <p v-if="form.recentlySuccessful">Flash message to show success!</p>
+</x-splade-form>
+```
+
 ## Submit on change
 
 Sometimes you want to submit the form whenever a value changes, for example, on a settings page that you want to save immediately. For this, you may use the `submit-on-change` attribute.
@@ -157,6 +182,26 @@ In addition, you may optionally specify one or more values (with an `array` or `
 <x-splade-form :submit-on-change="['name', 'email']">
 ```
 
+While this is great for elements like checkboxes, radios, and selects, it might lead to a bad user experience when applied to text inputs, as the form disables user input on submission. To overcome this, you may use the `background` attribute. This prevents to form from disabling user input and leaves the state properties (`processing`, `wasSuccessful`, and `recentlySuccessful`) untouched. In addition, to prevent the form from submitting on every keystroke, you may use the `debounce` attribute to set a debounce time in milliseconds:
+
+```blade
+<x-splade-form submit-on-change background debounce="500">
+    <input v-model="form.message" />
+</x-splade-form>
+```
+
+If you still want to indicate whether the form is processing, you may use the `processingInBackground` property:
+
+```blade
+<x-splade-form submit-on-change background debounce="500">
+    <input v-model="form.message" />
+
+    <p v-if="form.processingInBackground">Saving message in background...</p>
+
+    <button type="submit">Send message</button>
+</x-splade-form>
+```
+
 ## Reset and restore form
 
 You may use the `form.reset` method to clear all form data.
@@ -203,21 +248,6 @@ You may choose to reset or restore the form data automatically. You can do this
 <x-splade-form stay restore-on-success>
 ```
 
-## State
-
-There are several props that you can use to show the state of the form:
-
-```blade
-<x-splade-form>
-    <p v-if="form.processing">Submitting the data...</p>
-</x-splade-form>
-
-<x-splade-form stay>
-    <p v-if="form.wasSuccessful">Successfully submitted!</p>
-
-    <p v-if="form.recentlySuccessful">Flash message to show success!</p>
-</x-splade-form>
-```
 
 ## Form API
 

x-link.md

@@ -27,6 +27,8 @@ In addition, you may customize the confirmation dialog:
 </Link>
 ```
 
+Instead of the `confirm` attribute, you may also use the `confirm-danger` attribute to render a red confirmation button.
+
 ## Redirecting To External Domains
 
 When the URL is outside your application pointing to an external domain, you'd typically use a regular `<a>` element. Still, you may use the `away` attribute on the `Link` component. This can be useful when you have wrapped the component into another component and don't want to change the tag dynamically.

x-modal.md

@@ -68,6 +68,12 @@ By default, the modal is vertically centered. However, you may customize this wi
 <x-splade-modal position="top">
 ```
 
+The slideover opens on the right side by default, but you may change that as well with the `position` attribute:
+
+```blade
+<x-splade-modal position="left">
+```
+
 ## Close Button
 
 The modal and slideover have a *close button*, which you can disable with the `close-button` attribute.
@@ -115,4 +121,10 @@ To use a slideover, you must put the attribute on the `x-splade-component` inste
 <x-splade-modal name="refund-info" slideover max-width="lg">
     <p>...</p>
 </x-splade-modal>
-```
+```
+
+Additionally, it's possible to immediately show the modal on page load with the `opened` attribute:
+
+<x-splade-modal opened>
+    <pre>secret-token</pre>
+</x-splade-modal>