docs: migrate docs from website

Author: tobimori

docs/1_setup/2_configuration.md

@@ -0,0 +1,42 @@
+---
+title: Configuration
+description: Configure DreamForm to your needs
+---
+
+## Configuration Options
+
+### Required Settings
+
+| Option | Default | Accepts | Description |
+| --- | --- | --- | --- |
+| tobimori.dreamform.secret | `null` | `string|callable` | Encryption secret for published values (required for HTMX and API modes) |
+
+### Optional Settings
+
+| Option | Default | Accepts | Description |
+| --- | --- | --- | --- |
+| tobimori.dreamform.mode | `'prg'` | `'prg'|'api'|'htmx'` | Set the submission mode for all form submissions |
+| tobimori.dreamform.multiStep | `true` | `boolean` | Enable or disable multi-step forms |
+| tobimori.dreamform.storeSubmissions | `true` | `boolean` | Whether to store submissions as pages in Kirby |
+| tobimori.dreamform.debug | `fn () => option('debug')` | `boolean|callable` | If enabled, sensitive errors are shown on form submission |
+| tobimori.dreamform.layouts | `['1/1', '1/2, 1/2']` | `array` | Enabled layouts for the form builder |
+| tobimori.dreamform.page | `page://forms` | `string` | The page where all forms are stored |
+| tobimori.dreamform.integrations.gravatar | `true` | `boolean` | If enabled, submissions with email fields fetch an avatar from Gravatar to show in the panel |
+
+## Example Configuration
+
+```php
+// site/config/config.php
+
+return [
+  'tobimori.dreamform' => [
+    'secret' => fn () => env('DREAMFORM_SECRET'),
+    'mode' => 'htmx',
+    'debug' => false,
+    'layouts' => ['1/1', '1/2, 1/2', '1/3, 1/3, 1/3'],
+    'guards' => [
+      'available' => ['csrf', 'honeypot', 'turnstile']
+    ]
+  ]
+];
+```

docs/2_fields/0_what-are-fields.md

@@ -0,0 +1,56 @@
+---
+title: What are Fields?
+description: Learn about the core building blocks of your forms
+---
+
+Fields are the core building blocks of your form. They define what data, how it can be submitted, as well as validate & sanitize it.
+
+A field doesn't have to be a form input, it can also be a button or an image, although they will always follow the same syntax as a normal field.
+
+## Available Fields
+
+### Built-in Fields
+
+* [Button](1_button.md) - Button field for form navigation and submission
+* [Text](2_text.md) - Single-line text input field
+* [Multi-line Text](3_multi-line-text.md) - Multi-line text input field for longer content
+* [Number](4_number.md) - Number input field for numeric values
+* [Email](5_email.md) - Email input field with validation
+* [Checkboxes](6_checkboxes.md) - Multiple choice selection field
+* [Radio](7_radio.md) - Single choice selection field
+* [Select](8_select.md) - Dropdown selection field
+* [Pages](9_pages.md) - Dropdown populated with Kirby pages
+* [Hidden](10_hidden.md) - Hidden field for URL parameters and data storage
+* [File Upload](11_file-upload.md) - File upload field for documents and media
+
+### Fields created by the Community
+
+* [Date Field using Air DatePicker by Tobias Möritz](https://github.com/tobimori/dreamform-date-field)
+* [Date Field by Till Schander](https://github.com/tillschander/dreamform-datefield)
+* [Info Field by Moinframe](https://github.com/moinframe/kirby-dreamform-info-field)
+
+### Creating Custom Fields
+
+* [Custom Fields](12_custom.md) - Learn how to create your own custom fields
+
+## Configuring Fields
+
+By default, all registered and configured fields are available, but you can customize the available fields in your `config.php`.
+
+```php
+// site/config/config.php
+
+return [
+  'tobimori.dreamform' => [
+    'fields' => [
+      'available' => ['text', 'textarea', 'select', 'checkboxes', /* other guards here */ ],
+    ],
+  ],
+];
+```
+
+### Options
+
+| Option | Default | Accepts | Description |
+| --- | --- | --- | --- |
+| tobimori.dreamform.fields.available | `true` | `boolean|array` | Available fields, true enables all fields |

docs/2_fields/10_hidden.md

@@ -0,0 +1,28 @@
+---
+title: Hidden
+description: Hidden field for URL parameters and data storage
+---
+
+The hidden field allows you to access and store values from the URL parameters. Some common examples might be `ref` or `utm_content`. You can specify the respective key you want to capture.
+
+It maps to an `<input type="hidden">` element.
+
+![Hidden field example](hidden-field.png)
+
+In some instances, applying URL parameters as values might not work correctly due to caching. By default, Kirby should ignore the pages cache when an URL parameter is specified, but this is e.g. not the case for Staticache. If you encounter this issue, you can add a simple JavaScript that fills the inputs on the client-side.
+
+```javascript
+// Split the URL parameters into key-value pairs
+const params = new URLSearchParams(window.location.search.substring(1));
+
+// Loop through each key-value pair
+for (const [key, value] of params) {
+  // Find the input field with the matching name
+  const input = document.querySelector(`input[type="hidden"][name="${key}"]`);
+
+  // If the input field exists, set its value
+  if (input) {
+    input.value = value;
+  }
+}
+```

docs/2_fields/11_file-upload.md

@@ -0,0 +1,70 @@
+---
+title: File Upload
+description: File upload field for documents and media
+---
+
+The File Upload allows your user to upload files like images, PDF documents, or archives with a form submission.
+
+![File upload field example](file-upload-field.png)
+
+Clicking on the Edit button, you can customize the maximum file size and the allowed document types.
+
+PHP has a maximum file size in the `php.ini` config that will take preference over the specified file size in the fields config. To increase it, set the `upload_max_filesize` & `post_max_size` to your desired values.
+
+It's important to keep in mind that the **file upload is not available when disabling storing submisisons.**
+
+## Protecting files
+
+Since Kirby copies all files to the media folder, **they're publicly accessible by default.** If you're handling sensitive data, follow along. The Kirby documentation has great [Cookbook guide](https://getkirby.com/docs/cookbook/security/files-firewall) on how to protect files. You can adapt it to work with DreamForm files by checking for the `dreamform-upload` blueprint. In the end, it could look lke this:
+
+```php
+<?php
+
+use Kirby\Toolkit\Str;
+use Kirby\Uuid\Uuid;
+use Kirby\Cms\App;
+
+App::plugin('dreamform/files-firewall', [
+  'routes' => [
+    [
+      'pattern' => '_form/(:any)',
+      'action'  => function ($filename) {
+        if (
+          kirby()->user() &&
+          $file = Uuid::for("file://{$filename}")?->model()
+        ) {
+          /** @var \Kirby\Cms\File $file */
+          return $file->download();
+        }
+
+        return site()->errorPage();
+      },
+    ],
+  ],
+  'components' => [
+    'file::url' => function ($kirby, $file) {
+      if ($file->template() === 'dreamform-upload') {
+        return $kirby->url() . '/_form/' . Str::replace($file->uuid()->toString(), 'file://', '');
+      }
+
+      return $file->mediaUrl();
+    },
+    'file::version' => function ($kirby, $file, array $options = []) {
+      static $original;
+
+      // if the file is protected, return the original file
+      if ($file->template() === 'dreamform-upload') {
+        return $file;
+      }
+
+      // if static $original is null, get the original component
+      if ($original === null) {
+        $original = $kirby->nativeComponent('file::version');
+      }
+
+      // and return it with the given options
+      return $original($kirby, $file, $options);
+    }
+  ],
+]);
+```