From d4f34b2ec4de2614558216d636297aa45b1ea217 Mon Sep 17 00:00:00 2001 From: Sergey Moiseev Date: Thu, 29 Aug 2024 15:38:48 +0300 Subject: [PATCH 1/4] Draft Library Documentation (#8) --- Gemfile.lock | 2 +- README.md | 121 ++++++++++++++++++++++++++ app/views/components/_input.html.erb | 2 +- app/views/components/_select.html.erb | 2 +- 4 files changed, 124 insertions(+), 3 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 29a7e77..12ce7dd 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ PATH remote: . specs: - turbo_material (0.2.10) + turbo_material (0.2.12) importmap-rails (~> 2.0.1) rails (~> 7.1, >= 7.1.2) stimulus-rails (~> 1.3) diff --git a/README.md b/README.md index 535ac9d..3d793e8 100644 --- a/README.md +++ b/README.md @@ -232,6 +232,127 @@ Or install it yourself as: $ gem install turbo_material ``` +## Available components + +- [Input](#input) +- [Checkbox](#checkbox) +- [Radio button](#radio-button) +- [Switch button](#switch-button) +- [Select](#select) + +### Input + +Implements [Material Design Textfield](https://github.com/material-components/material-components-web/tree/master/packages/mdc-textfield) component. + +```erb +<%= material_input label: 'New password', name: 'password', required: true, parent: resource, + id: "user-password", form: form, type: 'password', + value: resource.password %> +``` + +#### Options + +| Option | Type | Description | +| --- | --- | --- | +| `label` | String | Input label text | +| `name` | String | Name of the input | +| `required` | Boolean | Whether the input is required | +| `disabled` | Boolean | Whether the input is disabled | +| `parent` | Object | Parent object | +| `id` | String | ID of the input | +| `form` | Object | Form object | +| `type` | String | Type of the input conforming to HTML input type specification (e.g., text, password) | +| `value` | String | Value of the input | +| `style` | String | Style of the input (filled, outlined) | +| `custom_css` | String | Custom CSS class | +| `custom_controller` | String | Custom Stimulus controller | + + +### Checkbox + +Implements [Material Design Checkbox](https://github.com/material-components/material-components-web/tree/master/packages/mdc-checkbox) component. + +```erb +<%= material_checkbox name: 'remember_me', id: 'remember-me', form: form, label: 'Remember me' %> +``` + +#### Options + +| Option | Type | Description | +| --- | --- | --- | +| `name` | String | Checkbox name | +| `id` | String | Checkbox ID | +| `form` | Object | Form object | +| `label` | String | Checkbox label | +| `disabled` | Boolean | Whether the checkbox is disabled | +| `checked` | Boolean | Whether the checkbox is checked | +| `checked_value` | String | Value when the checkbox is checked | +| `unchecked_value` | String | Value when the checkbox is unchecked | +| `source_override` | String | Used to populate checkbox value from another form field | + +### Radio button + +Implements [Material Design Radio button](https://github.com/material-components/material-components-web/tree/master/packages/mdc-radio) component. + +```erb +<%= material_radio name: 'option', id: 'option-1', form: form, label: 'Option 1' %> +``` + +#### Options + +| Option | Type | Description | +| --- | --- | --- | +| `name` | String | Radio button name | +| `id` | String | Radio button ID | +| `form` | Object | Form object | +| `label` | String | Radio button label | +| `disabled` | Boolean | Whether the radio button is disabled | +| `value` | String | Radio button value | +| `parent` | Object | Radio button parent | + +### Switch button + +Implements [Material Design Switch button](https://github.com/material-components/material-components-web/tree/master/packages/mdc-switch) component. + +```erb +<%= material_switch label: 'Switch', true_label: 'On', false_label: 'Off' %> +``` + +#### Options + +| Option | Type | Description | +| --- | --- | --- | +| `label` | String | Switch button label text | +| `disabled` | Boolean | Whether the switch is disabled | +| `required` | Boolean | Whether the switch is required | +| `true_label` | String | Text that displays when switch is on | +| `false_label` | String | Text that displays when switch is off | + +### Select + +Implements [Material Design Select](https://github.com/material-components/material-components-web/tree/master/packages/mdc-select) component. + +```erb +<%= material_select name: 'country', id: 'country', form: form, options: Carmen::Country.all, selected_text: 'Select country' %> +``` + +#### Options + +| Option | Type | Description | +| --- | --- | --- | +| `name` | String | Select name | +| `id` | String | Select ID | +| `disabled` | Boolean | Whether the select is disabled | +| `required` | Boolean | Whether the select is required | +| `form` | Object | Form object | +| `options` | Array | Select options | +| `selected_text` | String | Text that displays when nothing is selected | +| `fixed` | Boolean | Whether select uses `mdc-menu-surface--fixed` or `mdc-menu-surface--fullwidth` | +| `outlined` | Boolean | Whether the select is outlined | +| `additional_classes` | String | Additional CSS classes for select | +| `hint` | String | Hint text to display | + + ## Lookbook documentation for components Gem implements [Lookbook](https://lookbook.build) documentation for all components. To use it in the application, add `gem 'lookbook'` to your Gemfile and run `bundle install`. Then add following to your `config/application.rb`: diff --git a/app/views/components/_input.html.erb b/app/views/components/_input.html.erb index 52181c9..44f4bb0 100644 --- a/app/views/components/_input.html.erb +++ b/app/views/components/_input.html.erb @@ -1,4 +1,4 @@ -<%# locals: (form:, custom_controller: nil, custom_css: nil, disabled: false, required: false, name:, label: nil, id:, checked: false, frame: nil, provide_hidden: false, value: nil, type: 'text', data: {}, min: nil, max: nil, helper: nil, parent: nil, style: 'filled', leading_icon: nil, trailing_icon: nil, leading_icon_data: {}, trailing_icon_data: {}) %> +<%# locals: (form:, custom_controller: nil, custom_css: nil, disabled: false, required: false, name:, label: nil, id:, frame: nil, provide_hidden: false, value: nil, type: 'text', data: {}, min: nil, max: nil, helper: nil, parent: nil, style: 'filled', leading_icon: nil, trailing_icon: nil, leading_icon_data: {}, trailing_icon_data: {}) %>