Skip to content

Commit 78e9e59

Browse files
excid3excid3
committed
Break out docs to their own pages
1 parent 2bd059b commit 78e9e59

23 files changed

+452
-596
lines changed

‎README.md

Lines changed: 16 additions & 491 deletions
Large diffs are not rendered by default.

‎docs/alert.gif

28.6 KB
Loading

‎docs/alert.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Alert Component
2+
3+
![alert](alert.gif)
4+
5+
A toast-like alert notification that slides into view at the top of the screen when rendered, and slides back out of view when the "X" button is clicked/pressed.
6+
7+
## Usage
8+
9+
```javascript
10+
import { Alert } from "tailwindcss-stimulus-components"
11+
application.register('alert', Alert)
12+
```
13+
14+
To customize the appearance of alerts based on the kind of alert it is, you can do something like this in: `app/helpers/application_helper.rb`
15+
16+
```ruby
17+
module ApplicationHelper
18+
def tailwind_classes_for(flash_type)
19+
{
20+
notice: "bg-green-400 border-l-4 border-green-700 text-white",
21+
error: "bg-red-400 border-l-4 border-red-700 text-black",
22+
}.stringify_keys[flash_type.to_s] || flash_type.to_s
23+
end
24+
end
25+
```
26+
27+
And then add something like this either directly in the layout file, or in a partial that's rendered directly by the layout:
28+
29+
```html
30+
<div class="fixed inset-x-0 top-0 flex items-end justify-right px-4 py-6 sm:p-6 justify-end z-30 pointer-events-none">
31+
<div data-controller="alert" class="max-w-sm w-full shadow-lg rounded px-4 py-3 rounded relative bg-green-400 border-l-4 border-green-700 text-white pointer-events-auto">
32+
<div class="p-2">
33+
<div class="flex items-start">
34+
<div class="ml-3 w-0 flex-1 pt-0.5">
35+
<p class="text-sm leading-5 font-medium">
36+
Stimulus is the JS of the future!
37+
</p>
38+
</div>
39+
<div class="ml-4 flex-shrink-0 flex">
40+
<button data-action="alert#close" class="inline-flex text-white focus:outline-none focus:text-gray-300 transition ease-in-out duration-150">
41+
<svg class="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
42+
<path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"/>
43+
</svg>
44+
</button>
45+
</div>
46+
</div>
47+
</div>
48+
</div>
49+
</div>
50+
```
51+
52+
Alerts are set up to slide into view from the top-right side of the screen. Clicking on the "X" button will cause the alert to slide back out of view and be removed from the DOM.
53+
54+
## Options
55+
56+
- `data-alert-dismiss-after-value` can be provided to make the alert dimiss after x miliseconds. Default is `undefined`.
57+
- `data-alert-show-delay-value` can be set to tell the alert to show itself after x miliseconds. Defaults to `0` miliseconds.
58+
- `data-alert-remove-delay-value` can be set to tell the alert to hide itself after x milisconds. Defaults to `1100` miliseconds.

‎docs/autosave.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Autosave Component
2+
3+
Autosubmits forms for autosave functionality. Form submissions are debounced automatically with `1000ms` delay by default.
4+
5+
## Usage
6+
7+
```js
8+
import { Autosave } from "tailwindcss-stimulus-components"
9+
application.register('autosave', Autosave)
10+
```
11+
12+
Then apply it to a form. This example will fire the save event on keyup inside the title field.
13+
14+
```erb
15+
<%= form_with(model: post, data: { controller: "autosave", autosave_target: "form", action: "turbo:submit-end->autosave#success turbo:fetch-request-error->autosave#error" }) do |form| %>
16+
<div class="form-group">
17+
<%= form.label :title %>
18+
<%= form.text_field :title, class: 'form-control', data: { action: "keyup->autosave#save" } %>
19+
</div>
20+
21+
<div data-autosave-target="status"></div>
22+
23+
<%= form.submit %>
24+
<% end %>
25+
```
26+
27+
The form is submitted using `form.requestSubmit()` and Turbo events are fired when the request is failed or completed. These different events are used to trigger the error or success messages accordingly.
28+
29+
30+
## Handling the form submission server-side
31+
32+
Your server side should check the `params[:commit]` text (the value submitted by clicking the button) to see whether or not it should save as a draft or actually publish the record.
33+
34+
We recommend using a gem like Draftsman to help make the backend easier.

‎docs/color-preview.gif

351 KB
Loading

‎docs/color-preview.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Color Picker and Preview
2+
3+
A color picker preview where you can choose to have the color or backgroundColor get updated based on the result of a color picker.
4+
5+
It also supports ensuring the foreground text is always readable by performing a YIQ calculation to set the text to black or white based on the contrast of the color and backgroundColor.
6+
7+
## Usage
8+
9+
```html
10+
<div class="mt-3 flex items-center" data-controller="color-preview">
11+
<p data-color-preview-target="preview" class="h-10 w-10 mr-2 rounded-full text-2xl text-white text-center" style="background-color: #ba1e03; color: #fff; padding-top: 1px;">A</p>
12+
<span class="ml-2">
13+
<div class="flex rounded-md shadow-sm">
14+
<span class="inline-flex items-center px-3 rounded-l-md border border-r-0 border-gray-300 bg-gray-50 text-gray-500">#</span>
15+
<input data-action="input->color-preview#update"
16+
data-color-preview-target="color"
17+
id="hex_color_bg"
18+
name="hex_color_bg"
19+
type="color"
20+
value="#ba1e03"
21+
class="focus:ring-indigo-500 focus:border-indigo-500 block shadow-sm sm:text-sm border-gray-300 flex-1 rounded-r-md mt-0 w-24 h-8 px-1 py-1 border" />
22+
</div>
23+
</span>
24+
</div>
25+
```
26+
27+
This will update the `backgroundColor` by default but you can choose to have the color preview update the `color` instead by setting the `data-color-preview-style-value="color"` attribute of the color preview controller.

‎docs/dropdown.gif

16.9 KB
Loading

‎docs/dropdown.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Dropdown Component
2+
3+
![dropdown](dropdown.gif)
4+
5+
## Usage
6+
7+
```javascript
8+
import { Dropdown } from "tailwindcss-stimulus-components"
9+
application.register('dropdown', Dropdown)
10+
```
11+
12+
```html
13+
<div data-controller="dropdown" data-action="click->dropdown#toggle click@window->dropdown#hide">
14+
<div id="dropdown-button" class="relative inline-block">
15+
<div role="button" tabindex="0" data-dropdown-target="button" class="inline-block select-none">
16+
<span class="appearance-none flex items-center inline-block">
17+
<span>Dropdown Example</span>
18+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" class="fill-current h-4 w-4"><path d="M9.293 12.95l.707.707L15.657 8l-1.414-1.414L10 10.828 5.757 6.586 4.343 8z"></path></svg>
19+
</span>
20+
</div>
21+
<div data-dropdown-target="menu"
22+
data-transition-enter="transition ease-out duration-200"
23+
data-transition-enter-from="opacity-0 translate-y-1"
24+
data-transition-enter-to="opacity-100 translate-y-0"
25+
data-transition-leave="transition ease-in duration-150"
26+
data-transition-leave-from="opacity-100 translate-y-0"
27+
data-transition-leave-to="opacity-0 translate-y-1"
28+
class="hidden absolute top-4 right-0 z-10 mt-5 flex w-screen max-w-max">
29+
<div class="text-sm bg-white shadow-lg rounded border overflow-hidden w-32">
30+
<a href="#" class='no-underline block pl-4 py-2 text-gray-900 bg-white hover:bg-gray-100 whitespace-no-wrap'>Account</a>
31+
<a href="#" class='no-underline block pl-4 py-2 text-gray-900 bg-white hover:bg-gray-100 whitespace-no-wrap'>Billing</a>
32+
<a href="#" class='no-underline block pl-4 py-2 text-gray-900 bg-white hover:bg-gray-100 whitespace-no-wrap border-t'>Sign Out</a>
33+
</div>
34+
</div>
35+
</div>
36+
</div>
37+
```
38+
39+
Dropdowns are set up to toggle if you click on the dropdown button or any of the
40+
options with in the dropdown menu (via `data-action="click->dropdown#toggle`).
41+
It will also close if you click anywhere outside of the dropdown. This is
42+
done using a window click event to check if the user clicked outside the
43+
dropdown (`data-action="click@window->dropdown#hide"`).
44+
45+
Users can also focus on the dropdown button if `tabindex="0"` is included. They can toggle the dropdown with Space or Enter if the attribute `data-dropdown-target="button"` is included on the button.
46+
47+
If you want a dropdown to be opened on page load you can set the ```data-dropdown-open-value="true"``` as a data attribute.
48+
49+
The code above will toggle the dropdown component, if you needed to only perform a single action, such as `show` or `hide`. the dropdown component exposes such method.
50+
51+
```html
52+
data-action="click->dropdown#show"
53+
data-action="click->dropdown#hide"
54+
```

‎docs/modal.gif

75.3 KB
Loading

‎docs/modal.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Modal Component
2+
3+
![modal](modal.gif)
4+
5+
## Usage
6+
7+
```javascript
8+
import { Modal } from "tailwindcss-stimulus-components"
9+
application.register('modal', Modal)
10+
```
11+
12+
```html
13+
<div data-controller="modal" data-action="keydown.esc->modal#close" tabindex="-1" class="relative z-10">
14+
<a href="#" data-action="click->modal#open" class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-3 px-6 rounded">Open Modal</a>
15+
16+
<!-- Modal Background -->
17+
<div class="hidden fixed inset-0 bg-black bg-opacity-80 overflow-y-auto flex items-center justify-center"
18+
data-modal-target="background"
19+
data-action="click->modal#closeBackground"
20+
data-transition-enter="transition-all ease-in-out duration-300"
21+
data-transition-enter-from="bg-opacity-0"
22+
data-transition-enter-to="bg-opacity-80"
23+
data-transition-leave="transition-all ease-in-out duration-300"
24+
data-transition-leave-from="bg-opacity-80"
25+
data-transition-leave-to="bg-opacity-0">
26+
27+
<!-- Modal Container -->
28+
<div data-modal-target="container" class="max-h-screen w-full max-w-lg relative">
29+
<!-- Modal Card -->
30+
<div class="m-1 bg-white rounded shadow">
31+
<div class="p-8">
32+
<h2 class="text-xl mb-4">Large Modal Content</h2>
33+
<p class="mb-4">This is an example modal dialog box.</p>
34+
35+
<div class="flex justify-end items-center flex-wrap mt-6">
36+
<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded" data-action="click->modal#close:prevent">Close</button>
37+
</div>
38+
</div>
39+
</div>
40+
</div>
41+
</div>
42+
</div>
43+
```
44+
45+
`data-modal-restore-scroll-value` may be set to `false` to disable
46+
restoring scroll position.

‎docs/popover.gif

36.7 KB
Loading

‎docs/popover.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Popover Component
2+
3+
![popover](popover.gif)
4+
5+
## Usage
6+
7+
```javascript
8+
import { Popover } from "tailwindcss-stimulus-components"
9+
application.register('popover', Popover)
10+
```
11+
12+
```html
13+
<p>
14+
Beginning in 2015, Google introduced what is called the
15+
<div class="popover inline-block" data-controller="popover" data-popover-translate-x="0" data-popover-translate-y="-128%" data-action="mouseover->popover#mouseOver mouseout->popover#mouseOut">
16+
<span class="underline">'local snack pack',</span>
17+
<div class="content hidden absolute max-w-xs bg-gray-300 rounded p-2" data-popover-target="content">
18+
Terrible name - we know. But the biggest name in SEO came up with it.
19+
</div>
20+
</div>
21+
which shows you local search results before normal organic results.
22+
</p>
23+
```
24+
25+
`data-popover-target="content"` defines which element will contain the actual content in the popover.
26+
27+
`data-alert-dismiss-after-value` can be provided to make the popover dimiss after x miliseconds. Default is `undefined`.

‎docs/slideover.gif

152 KB
Loading

‎docs/slideover.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Slideover Component
2+
3+
![slideover](slideover.gif)
4+
5+
## Usage
6+
7+
```js
8+
import { Slideover } from "tailwindcss-stimulus-components"
9+
application.register('slideover', Slideover)
10+
```
11+
12+
```html
13+
<div class="container mx-auto p-8" data-controller="slideover" data-action="keydown.esc->modal#close" tabindex="-1">
14+
<!-- begin sidebar/slideover -->
15+
<div id="sidebar-mobile">
16+
<div data-slideover-target="overlay"
17+
class="hidden fixed inset-0 flex z-40"
18+
data-transition-enter="transition ease-out duration-200"
19+
data-transition-enter-from="opacity-0"
20+
data-transition-enter-to="opacity-100"
21+
data-transition-leave="transition ease-in duration-150"
22+
data-transition-leave-from="opacity-100"
23+
data-transition-leave-to="opacity-0"
24+
>
25+
<div class="fixed inset-0">
26+
<div class="absolute inset-0 bg-gray-600 opacity-75"></div>
27+
</div>
28+
<div data-slideover-target="menu"
29+
class="hidden relative flex-1 flex flex-col max-w-xs w-full pt-5 pb-4 bg-gray-800"
30+
data-transition-enter="transition ease-out duration-200"
31+
data-transition-enter-from="opacity-0 -translate-x-full"
32+
data-transition-enter-to="opacity-100 translate-x-0"
33+
data-transition-leave="transition ease-in duration-150"
34+
data-transition-leave-from="opacity-100 translate-x-0"
35+
data-transition-leave-to="opacity-0 -translate-x-full"
36+
>
37+
<div class="absolute top-0 right-0 -mr-14 p-1">
38+
<button data-action="slideover#toggle" class="flex items-center justify-center h-12 w-12 rounded-full focus:outline-none focus:bg-gray-600" aria-label="Close sidebar">
39+
<svg class="h-6 w-6 text-white" stroke="currentColor" fill="none" viewBox="0 0 24 24">
40+
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
41+
</svg>
42+
</button>
43+
</div>
44+
<div class="flex-shrink-0 flex items-center px-4">
45+
<h1 class="text-white text-2xl font-bold">Sidebar</h1>
46+
</div>
47+
<div class="mt-5 flex-1 h-0 overflow-y-auto">
48+
<nav class="px-2 space-y-1">
49+
</nav>
50+
</div>
51+
</div>
52+
<div class="flex-shrink-0 w-14">
53+
<!-- Dummy element to force sidebar to shrink to fit close icon -->
54+
</div>
55+
</div>
56+
</div>
57+
<!-- end sidebar/slideover -->
58+
59+
<!-- main content -->
60+
<button data-action="click->slideover#toggle click@window->slideover#hide" class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-3 px-6 rounded">
61+
<span>Open Slideover</span>
62+
</button>
63+
</div>
64+
```
65+
66+
Slideovers are glorified dropdowns that include an additional overlay. Thus, the setup is equivalent to that of dropdowns, albeit you must specify an `overlay` target. Animations are annotated similarly to dropdowns, just separate the `classList`s of menu and overlay with a comma `,`:
67+
68+
```html
69+
data-slideover-invisible-class="-translate-x-full,opacity-0"
70+
data-slideover-visible-class="translate-x-0,opacity-100"
71+
data-slideover-entering-class=""
72+
data-slideover-enter-timeout="300,300"
73+
data-slideover-leaving-class=""
74+
data-slideover-leave-timeout="300,0"
75+
```

‎docs/tabs.gif

7.05 KB
Loading

‎docs/tabs.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Tabs Component
2+
3+
![tabs](tabs.gif)
4+
5+
## Usage
6+
7+
```javascript
8+
import { Tabs } from "tailwindcss-stimulus-components"
9+
application.register('tabs', Tabs)
10+
```
11+
12+
```html
13+
<div data-controller="tabs" data-tabs-active-tab="-mb-px border-l border-t border-r rounded-t">
14+
<ul class="list-reset flex border-b">
15+
<li class="-mb-px mr-1" data-tabs-target="tab" data-action="click->tabs#change">
16+
<a class="bg-white inline-block py-2 px-4 text-blue-500 hover:text-blue-700 font-semibold no-underline" href="#">Active</a>
17+
</li>
18+
<li class="mr-1" data-tabs-target="tab" data-action="click->tabs#change">
19+
<a class="bg-white inline-block py-2 px-4 text-blue-500 hover:text-blue-700 font-semibold no-underline" href="#">Tab</a>
20+
</li>
21+
<li class="mr-1" data-tabs-target="tab" data-action="click->tabs#change">
22+
<a class="bg-white inline-block py-2 px-4 text-blue-500 hover:text-blue-700 font-semibold no-underline" href="#">Tab</a>
23+
</li>
24+
<li class="mr-1">
25+
<a class="bg-white inline-block py-2 px-4 text-gray-300 font-semibold no-underline" href="#">Tab</a>
26+
</li>
27+
</ul>
28+
29+
<div class="hidden py-4 px-4 border-l border-b border-r" data-tabs-target="panel">
30+
Tab panel 1
31+
</div>
32+
33+
<div class="hidden py-4 px-4 border-l border-b border-r" data-tabs-target="panel">
34+
Tab panel 2
35+
</div>
36+
37+
<div class="hidden py-4 px-4 border-l border-b border-r" data-tabs-target="panel">
38+
<iframe width="560" height="315" src="https://www.youtube.com/embed/y3niFzo5VLI" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
39+
</div>
40+
</div>
41+
```
42+
43+
`data-tabs-target="tab"` defines which element is marked as a tab. The index of the tab is used to determine which panel to make visible.
44+
45+
`data-tabs-target="panel"` defines which panel is visible based upon the currently selected tab.
46+
47+
`data-tabs-active-tab-class` defines the list of classes that will be added/removed from the active tab when the active tab changes.
48+
49+
`data-tabs-inactive-tab-class` defines the list of classes that will be added/removed from the inactive tab when the active tab changes.
50+
51+
`data-tabs-index-value="1"` can be used to set the selected tab when the controller connects.
52+
53+
`data-tabs-update-anchor-value="true"` can be used to update the URL anchor when the tab changes.
54+
55+
##### Changing tabs from other places
56+
57+
If you'd like to change the tab from a button or link outside of the tabs, you can call the same method and assign either `data-id` or `data-index` to select the tab.
58+
59+
```html
60+
<a data-action="click->tabs#change" data-index="1">Change tab by data-index</a>
61+
62+
<a data-action="click->tabs#change" data-id="second">Change tab by data-id</a>
63+
```

‎docs/toggle.gif

19.3 KB
Loading

0 commit comments

Comments
 (0)