New component documentation

rawilk · rawilk · commit 5e0590d4644d · 2020-10-23T14:26:46.000-05:00
diff --git a/docs/components/checkbox-group.md b/docs/components/checkbox-group.md
@@ -1,6 +1,6 @@
 ---
 title: Checkbox Group
-sort: 9
+sort: 10
 ---
 
 ## Introduction
diff --git a/docs/components/checkbox.md b/docs/components/checkbox.md
@@ -1,6 +1,6 @@
 ---
 title: Checkbox
-sort: 8
+sort: 9
 ---
 
 ## Introduction
diff --git a/docs/components/custom-select.md b/docs/components/custom-select.md
@@ -0,0 +1,141 @@
+---
+title: Custom Select
+sort: 8
+---
+
+## Introduction
+
+Heavily based on [Tailwind UI's custom selects](https://tailwindui.com/components/application-ui/forms/select-menus), the `custom-select` component provides a nice alternative
+to the native select menu. Using this menu will provide your select menus with search functionalities and
+custom option markup while still providing usability functionalities such as keyboard navigation.
+
+## Installation
+
+The custom select component requires Alpine.js, as well as some custom JavaScript written into the package to work.
+Ensure you have the proper [directives](/docs/laravel-form-components/v1/installation#directives) in your layout file.
+In production, we recommend you install and compile the JavaScript libraries before you deploy:
+
+- [Alpine.js](https://github.com/alpinejs/alpine) `^2.7`
+
+## Basic Usage
+
+You can use the select menu by providing some basic options.
+
+```html
+<x-custom-select :options="['foo', 'bar']" />
+```
+
+This will output a custom select menu with options for `foo` and `bar`. The menu is toggled open and closed by using a `<button` element,
+and renders each option in an `<li>` tag inside of a `<ul>`. We have done our best to include all of the necessary aria attributes for
+accessiblity, but we are by no means accessibility experts. If you notice any accessibility issues, please submit a PR to the github
+repository to fix them.
+
+## Options
+
+There are multiple ways ot provide options to the component. The primary way is to provide an array of options via the `options` attribute.
+If you provide an array of strings, the component will use the strings as both the key and values of the options. For most cases however, you
+should provide an array of keyed arrays for each option, or you can even pass in an array of Eloquent models as options.
+
+```html
+<x-custom-select :options="[
+    ['value' => 'foo', 'text' => 'Foo'],
+    ['value' => 'bar', 'text' => 'Bar'],
+]" />
+
+<!-- using models -->
+<x-custom-select :options="[\App\Models\User::get(['id', 'name'])]" value-key="id" text-key="name" />
+```
+
+### Option Values & Text
+
+By default, the component will look for a `value` key for the option value, and a `text` key for the option text. When you are using Eloquent models
+for options, most of the time this won't work. For this reason, you can specify which keys the option should use for the value and text
+of the option via `value-key` and `text-key`.
+
+### Manually Creating Options
+
+Instead of passing in options to the custom select component, you can also create your own options via the default slot in the component by
+using the `custom-select-option` component. This component accepts an `option` attribute, and optionally a `value-key` attribute for the
+option's value, and `text-key` attribute for the option's text content.
+
+```html
+<x-custom-select-option :option="$user" value-key="id" text-key="name" />
+``` 
+
+The `custom-select-option` also has a default slot which will allow you to customize the markup of the content of the option.
+
+```html
+<x-custom-select-option :option="$user" value-key="id" text-key="name">
+    {{ $user->name }} <span class="text-xs">@{{ $user->email }}</span>
+</x-custom-select-option>
+```
+
+In either case, you still need to provide the `option` attribute, and then any value/text mapping you need. The `option` attribute
+is used by the package's JavaScript to help with keyboard navigation and also for local [filtering](#server-side-filtering) of options if you
+have filters enabled on the select.
+
+**Note:** Any content you place inside of the option will also be displayed on the button when the option is selected.
+
+### Disabling Options
+
+You may disable specific options by providing a boolean value of true to the component:
+
+```html
+<x-custom-select-option :option="$option" disabled />
+```
+
+### Opt Groups
+
+You can specify an option as an "optgroup" header by passing in a boolean true value to the `is-group` attribute:
+
+```html
+<x-custom-select-option is-group>Group Name</x-custom-select-option>
+```
+
+## Filtering
+
+You may provide search functionality on a custom select by setting `filterable` on the component to `true`.
+
+```html
+<x-custom-select :options="$options" filterable />
+```
+
+This will provide basic search functionality, which will hide any non-matching options as the user types.
+
+## Server-Side Filtering
+
+If you use Livewire, you can easily add server-side filtering of options via a custom `wire:filter` attribute on the component.
+
+```html
+<x-custom-select :options="$options" filterable wire:filter="selectSearch" />
+```
+
+Behind-the-scenes, the custom select component will convert that to a `wire:model` on the filter input in the select and bind it to
+your public property on your livewire component. From there, you can filter out your options based on the value of the filter. Modifiers
+such as `.lazy` or `.defer` are also supported on the `wire:filter` attribute.
+
+```html
+<x-custom-select :options="$options" filterable wire:filter.lazy="selectSearch" />
+```
+
+## Multiple Select
+
+You can easily make a select accept multiple selected options by using the `multiple` attribute.
+
+```html
+<x-custom-select :options="$options" multiple />
+```
+
+## Optional Selects
+
+For times that you want to allow users to clear the select option(s), you can mark a custom select as `optional`. This
+works for both single and multi-select modes, and provides a clear button next to the selected option text.
+
+```html
+<x-custom-select :options="$options" optional />
+```
+
+## Addons
+
+The custom select component supports leading addons, but since there are already elements appended to the end
+of the button trigger, trailing addons are not supported. For more information on addons, see [the input documentation](/docs/laravel-form-components/v1/components/input#addons).
diff --git a/docs/components/date-picker.md b/docs/components/date-picker.md
@@ -1,6 +1,6 @@
 ---
 title: Date Picker
-sort: 14
+sort: 15
 ---
 
 ## Introduction
diff --git a/docs/components/file-upload.md b/docs/components/file-upload.md
@@ -1,6 +1,6 @@
 ---
 title: File Upload
-sort: 15
+sort: 16
 ---
 
 ## Introduction
diff --git a/docs/components/filepond.md b/docs/components/filepond.md
@@ -1,6 +1,6 @@
 ---
 title: FilePond
-sort: 16
+sort: 17
 ---
 
 ## Introduction
diff --git a/docs/components/form-error.md b/docs/components/form-error.md
@@ -1,6 +1,6 @@
 ---
 title: Form Error
-sort: 11
+sort: 12
 ---
 
 ## Introduction
diff --git a/docs/components/label.md b/docs/components/label.md
@@ -1,6 +1,6 @@
 ---
 title: Label
-sort: 10
+sort: 11
 ---
 
 ## Introduction
diff --git a/docs/components/radio.md b/docs/components/radio.md
@@ -1,6 +1,6 @@
 ---
 title: Radio
-sort: 8
+sort: 9
 ---
 
 ## Introduction
diff --git a/docs/components/select.md b/docs/components/select.md
@@ -173,5 +173,5 @@ This will output:
 
 ## Reference
 
-Since the select component extends the [input component](/docs/laravel-form-errors/v1/components/input), you are able
+Since the select component extends the [input component](/docs/laravel-form-components/v1/components/input), you are able
 to do a lot of the same things you can with the input element, such as error handling and addons.
diff --git a/docs/components/timezone-select.md b/docs/components/timezone-select.md
@@ -1,6 +1,6 @@
 ---
 title: Timezone Select
-sort: 13
+sort: 14
 ---
 
 ## Introduction
diff --git a/docs/installation.md b/docs/installation.md
@@ -42,6 +42,11 @@ your closing `</body>` tag and **after** scripts from libraries like Livewire.
 **Note:** The `@fcStyles` directives **does not** include styles generated by Laravel Form Components. You will still need to include
 those in [a stylesheet manually](#styling).
 
+If you would like to only link to the JavaScript necessary for some package components, such as the custom select component, you may
+use the `@fcJavaScript` blade directive instead of `@fcScripts`. This is useful if you are compiling any third-party scripts
+yourself, and is recommended in production. You should not use both directives together regardless of how you choose
+to compile scripts.
+
 ## Production
 
 Even though these directives allow you to get up and running with the components quickly, **we recommend that you compile the 3rd
@@ -93,20 +98,49 @@ You can also choose to use different classes and views for components. This allo
 to either extend or completely change the component's functionality by using a custom class
 and/or view of your own.
 
+## Component JavaScript
+
+Some components, such as the [custom select component](/docs/laravel-form-components/v1/components/custom-select), require custom
+JavaScript to run. The JavaScript is extracted to an external file since it is pretty substantial and should be minified. If
+you are using any components that depend on this JavaScript, be sure you are pulling the scripts in through either the
+`@fcJavaScript` or `@fcScripts` blade directives in your layout file. See [directives](#directives) for more information.
+
+### Asset URL
+For cases where your app's root domain is not the correct path for retrieving assets, you may set a custom root path that
+FormComponents will use to link to its JavaScript assets. You may specify a custom root path either in the config file,
+or as a parameter option through the blade directive:
+
+In the config:
+
+```php
+[
+    // ...
+    'asset_url' => 'myapp.com/app',
+];
+```
+
+In your layouts:
+
+```html
+@fcJavaScript(['asset_url' => 'myapp.com/app'])
+<!-- or -->
+@fcScripts(false, ['asset_url' => 'myapp.com/app'])
+```
+
 ## Prefixing
 
 Using components from this library might conflict with other ones from a different
 library or components from our own app. To prevent this you can opt to prefixing
-Form Components components by default to prevent these collisions. You can do this by
+FormComponents components by default to prevent these collisions. You can do this by
 setting the `prefix` option in the config file:
 
 ```php
 <?php
 
 return [
-    ...
+    // ...
     'prefix' => 'tw',
-    ...
+    // ...
 ];
 ```
 
diff --git a/src/Components/Inputs/CustomSelect.php b/src/Components/Inputs/CustomSelect.php
@@ -8,6 +8,8 @@
 
 class CustomSelect extends Select
 {
+    protected static array $assets = ['alpine'];
+
     /** @var string|null */
     public $placeholder;
 

-Original file line number
+Diff line change
@@ @@ -1,6 +1,6 @@ @@
 ---
 title: Checkbox
 -sort: 8
 +sort: 9
 ---
 ## Introduction