--- url: https://ambiki.github.io/impulse_view_components/introduction/getting-started.md --- # Getting started ## Requirements * Ruby 3.4 or later, and Rails 7.1 or later. * [Bootstrap 4](https://getbootstrap.com/docs/4.6/)'s CSS. The components use its classes, such as `form-control`, `dropdown-menu`, `btn` and `spinner-border`. * [Bootstrap Icons](https://icons.getbootstrap.com/)' CSS, for the icons the components render, such as `bi-x`. * [Dart Sass](https://sass-lang.com/dart-sass/), if you compile the components' Sass. ## Install the gem Add the gem to your `Gemfile`: ```rb gem "impulse_view_components" ``` Then install it: ```bash bundle install ``` ## Require the engine Require the engine in `config/application.rb`: ```rb require "impulse/view_components/engine" ``` ## Install the JavaScript package The interactive components ship as custom elements, so you also need the npm package. It's built on [`@ambiki/impulse`](https://github.com/Ambiki/impulse) 2, which you install alongside it, so your own elements and the components share one copy: ```bash yarn add @ambiki/impulse-view-components @ambiki/impulse ``` ## Import the components Each component is imported individually, so you only ship what you use. For example, to use the [Select](/components/select) component: ```js import '@ambiki/impulse-view-components/autocomplete'; ``` To register every component at once, import the package itself: ```js import '@ambiki/impulse-view-components'; ``` See the **Imports** section on each component's page for the exact paths. ## Import the styles The styles are written in Sass on top of [Bootstrap 4](https://getbootstrap.com/docs/4.6/). Load Bootstrap's Sass functions, variables and mixins first (importing all of `bootstrap` does that), then the base styles once, then each component's styles: ```scss @import 'bootstrap/scss/functions'; @import 'bootstrap/scss/variables'; @import 'bootstrap/scss/mixins'; @import '@ambiki/impulse-view-components/base'; @import '@ambiki/impulse-view-components/autocomplete'; ``` To include every component's styles, import the package itself instead of `base` and each component: ```scss @import 'bootstrap/scss/functions'; @import 'bootstrap/scss/variables'; @import 'bootstrap/scss/mixins'; @import '@ambiki/impulse-view-components'; ``` These paths work through webpack's `sass-loader` and Vite. When you run the `sass` command line directly, as `cssbundling-rails` does, prefix each path with `pkg:` and pass `--pkg-importer=node`, which needs Dart Sass 1.71 or later: ```scss @import 'pkg:@ambiki/impulse-view-components/base'; @import 'pkg:@ambiki/impulse-view-components/autocomplete'; ``` A setup that only passes `--load-path=node_modules` can't read these paths, because it looks for files rather than reading the package's `exports`. It can keep importing the files directly: ```scss @import '@ambiki/impulse-view-components/dist/styles/variables'; @import '@ambiki/impulse-view-components/dist/styles/base'; @import '@ambiki/impulse-view-components/dist/elements/autocomplete'; ``` ### Without Sass If your app doesn't compile Sass, import the precompiled CSS, which holds every component's styles: ```js import '@ambiki/impulse-view-components/styles.css'; ``` It's built with Bootstrap's default variables, and doesn't include Bootstrap's component CSS, which you still load. Change colors and sizes through the CSS custom properties it defines on `:root`, such as `--awc-autocomplete-control-min-height`. ## Upgrading from `dist/` paths The package no longer exports paths that start with `@ambiki/impulse-view-components/dist/`. Use the shorter paths below. | Removed path | Use instead | |------------------------------------------------------------------|--------------------------------------------------------------------------------| | `…/dist/index.js` | `@ambiki/impulse-view-components` | | `…/dist/elements/`, `…/dist/elements//index.js` | `@ambiki/impulse-view-components/`, such as `…/popover` | | `import useFloatingUI from '…/dist/hooks/use_floating_ui'` | `import { useFloatingUI } from '@ambiki/impulse-view-components/hooks'` | | `import useOutsideClick from '…/dist/hooks/use_outside_click'` | `import { useOutsideClick } from '@ambiki/impulse-view-components/hooks'` | | `import useFocusOut from '…/dist/hooks/use_focus_out'` | `import { useFocusOut } from '@ambiki/impulse-view-components/hooks'` | | `@import '~…/dist/elements/'` | `@import '@ambiki/impulse-view-components/'` | | `@import '~…/dist/styles/variables'` and `'~…/dist/styles/base'` | `@import '@ambiki/impulse-view-components/base'` | | `import { cycle } from '…/dist/helpers/array'` | `import { cycle } from '@ambiki/impulse-view-components/helpers'` | | `import debounce from '…/dist/helpers/debounce'` | `import { debounce } from '@ambiki/impulse-view-components/helpers'` | | `import scrollLock from '…/dist/helpers/scroll_lock'` | `import { scrollLock } from '@ambiki/impulse-view-components/helpers'` | | Any other `…/dist/helpers/*`, or `…/dist/elements/autocomplete/` such as `ajax_search` | None. These modules are internal. | The Sass rows need a setup that reads the package's `exports`. A setup that only passes `--load-path` keeps importing the files, as [Import the styles](#import-the-styles) shows. Each element path exports its class by name, such as `AwcPopoverElement`, along with the types its properties use. `…/hooks` exports the types the hooks take and return, and `…/helpers` the [helpers](/helpers/) apps can use. --- --- url: https://ambiki.github.io/impulse_view_components/components/ajax-select.md --- # Ajax select Ajax select allows users to fetch a list of options from the server. ## Usage ```erb <%= render(Impulse::AjaxSelectComponent.new(:post, :person_id, :id, :name, src: "/users")) %> ``` ## Arguments ### Positional arguments | Name | Default | Description | | ------ | --------- | ------------- | | object_name | N/A | The name of the object. | | method_name | N/A | The name of the method. | | value_method | N/A | The method called on the `selected` object to read each option's value (e.g. `:id`). | | text_method | N/A | The method called on the `selected` object to read each option's display text (e.g. `:name`). | ### Keyword arguments | Name | Default | Description | | ------ | --------- | ------------- | | selected | `nil` | An object that responds to `value_method` and `text_method`, or an array of them for a `multiple` select. | | src | N/A | The endpoint to fetch the options from. | | param | `"q"` | The param that is appended when making a network request. Example: `/fruits?q=Guava`. | | size | `:md` | The size of the select control. One of `:sm`, `:md`, or `:lg`. | | name | `nil` | The name of the field. By default, Rails automatically creates a `name` string based on the `object_name` and `method_name`. | | input_id | `nil` | The id of the input field. | | placeholder | `nil` | The placeholder text that is displayed within the input field. | | include_hidden | `true` | Only applies to a `multiple` select. See the "Gotcha" section of the Rails [`select`](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-select) tag. | | disabled | `false` | Disables the select control. | | required | `false` | Makes the select control a required field. | | multiple | `false` | Whether multiple values can be selected or not. | | clearable | `true` | Whether the clear button should be shown or not. | | auto_size | `true` | If `true`, caps the listbox's height to the space between it and the edge of the viewport, so a long list scrolls instead of running off screen. | | auto_size_padding | `4` | The space in pixels to keep between the listbox and the edge of the viewport when `auto_size` is enabled. | Any other keyword arguments are passed to the `` element as HTML attributes, except `index`, `namespace`, `skip_default_ids` and `allow_method_names_outside_object`, which are passed to the Rails field helpers. ::: tip Note The endpoint receives the search text in `param`, such as `/fruits?q=gu`, and `?q=` when the listbox first opens. It responds with the HTML of the matching options. The request sends `Accept: text/fragment+html`, and a response that isn't 2xx shows the [error](#custom-error). ```erb <%= render(Impulse::Autocomplete::OptionComponent.new(value: "guava", text: "Guava")) %> <%= render(Impulse::Autocomplete::OptionComponent.new(value: "kiwi", text: "Kiwi")) %> ``` The `Impulse::Autocomplete::OptionComponent` also takes an optional `description` argument. ```erb <%= render(Impulse::Autocomplete::OptionComponent.new(value: "kiwi", text: "Kiwi", description: "This is a fruit.")) %> ``` ::: ## Examples ### Selecting an option Pass an object that responds to the `value_method` and the `text_method`. ```erb{8} <%= render( Impulse::AjaxSelectComponent.new( :post, :person_id, :id, :name, src: "/persons", selected: Person.find(1) ) ) %> ``` ::: tip In case of multiple select, pass an array of objects to the `selected` argument. ::: ### Custom blankslate A blankslate is displayed when the input's text does not match any of the options that are returned from the server. ```erb <%= render(Impulse::AjaxSelectComponent.new(:post, :person_id, :id, :name, src: "/persons")) do |c| %> <% c.with_blankslate { "We couldn't find what you're looking for!" } %> <% end %> ``` ### Custom error An error is displayed when the network request fails. ```erb <%= render(Impulse::AjaxSelectComponent.new(:post, :person_id, :id, :name, src: "/persons")) do |c| %> <% c.with_error { "We couldn't load the people. Please try again!" } %> <% end %> ``` ### Integrating with `form_with` Wrap your `ajax_select` tag with the `impulse_form_with` method. The `f.ajax_select` tag accepts the same [arguments](#arguments). Unlike `f.select`, it doesn't read the selection from the object, so pass `selected`. ```erb <%= impulse_form_with model: @user do |f| %> <%= f.ajax_select :fruit_id, :id, :name, selected: f.object.fruit, src: "/fruits" %> <% end %> ``` ### Translations The ajax select shares the select's blankslate, `impulse.autocomplete.blankslate` (see [Translations](./select.md#translations)), and adds its error: ```yaml en: impulse: autocomplete: error: An error occurred. Please try again! ``` ## Slots ### `with_blankslate` Overwrite the default blankslate message by passing a block. It takes no arguments. ### `with_error` Overwrite the default error message by passing a block. It takes no arguments. ## Imports ::: code-group ```js import '@ambiki/impulse-view-components/autocomplete'; ``` ```scss @import '@ambiki/impulse-view-components/autocomplete'; ``` ::: The styles need Bootstrap's Sass and the base styles loaded first. See [Import the styles](/introduction/getting-started#import-the-styles). ## JS API [Read here](../js-api/autocomplete.md). --- --- url: https://ambiki.github.io/impulse_view_components/components/anchor.md --- # Anchor `Impulse::AnchorComponent` renders an `` element: a **floating element**, such as a tooltip or a menu, that positions itself next to an **anchor** (another element on the page) and stays inside the viewport as the page scrolls or resizes. It is configured entirely with attributes, so it needs no JavaScript of your own. The anchor is often the **trigger** (the element that is clicked or hovered to show the floating element), but it doesn't have to be. For example, a menu opened by a chevron button can be anchored to the whole field. ::: tip Anchor or `useFloatingUI`? Use `Impulse::AnchorComponent` when you are writing markup and want something positioned. If you are writing your own [`impulse`](https://github.com/Ambiki/impulse) element that opens and closes a floating element, use the [`useFloatingUI`](../hooks/use-floating-ui.md) hook instead. Both share the same positioning logic and defaults. ::: ## Usage ```erb <%= render(Impulse::AnchorComponent.new(anchor_id: "anchor-button", active: true, class: "popover bs-popover-auto")) do %>
I am anchored to the button!
<% end %> ``` ## Arguments ### Keyword arguments | Name | Default | Description | | ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | anchor_id | N/A | The `id` of the element to position against. | | active | `false` | Whether the element is positioned when the page loads. Call [`start` and `stop`](../js-api/anchor.md) to change it from JavaScript. While `false`, the element stays where it was last placed, which before it first starts is the viewport's top-left corner. | | placement | `"bottom"` | The preferred placement. The actual placement may vary to keep the element inside the viewport. One of `"top"`, `"top-start"`, `"top-end"`, `"right"`, `"right-start"`, `"right-end"`, `"bottom"`, `"bottom-start"`, `"bottom-end"`, `"left"`, `"left-start"`, or `"left-end"`. | | strategy | `"fixed"` | The value of the `position` CSS property. One of `"absolute"` or `"fixed"`. | | distance | `0` | The distance in pixels away from the anchor. | | skidding | `0` | The distance in pixels along the anchor. | | sync | `nil` | Matches the element's size to the anchor's. One of `"height"`, `"width"`, or `"both"`. | | flip | `true` | Flips the element to another placement when the preferred one doesn't fit. | | flip_padding | `0` | The padding in pixels to keep from the viewport edge before flipping. Raised past `auto_size_padding` on the auto sized axis while `auto_size` is set. | | fallback_placements | `[]` | The placements to try, in order, when the preferred one doesn't fit. By default, the opposite side is tried. | | fallback_strategy | `"bestFit"` | What to do when no placement fits. `"bestFit"` uses the placement that fits best, and `"initialPlacement"` uses `placement`, or the side `keep_flipped` keeps. | | keep_flipped | `false` | Keeps the side the element flipped to until it's deactivated, instead of trying `placement` first on every reposition, so it doesn't jump back once its content shrinks. It still flips again when that side stops fitting. | | shift | `true` | Shifts the element along the anchor to keep it inside the viewport. | | shift_padding | `0` | The padding in pixels to keep from the viewport edge while shifting. | | auto_size | `nil` | Exposes the space available to the element as the `--awc-auto-size-height` and `--awc-auto-size-width` CSS custom properties. One of `"height"`, `"width"`, or `"both"`. | | auto_size_padding | `0` | The padding in pixels to keep from the viewport edge when measuring the available space. | | arrow_padding | `0` | The padding in pixels between the arrow and the edges of the element. | Any other keyword arguments are passed to the `` element as HTML attributes. ## Examples ### Adding an arrow Mark a child element with `data-arrow` to have it point at the anchor. The element's chosen placement is set as its `x-placement` attribute, which you can use to style the arrow for each side. ```erb{2} <%= render(Impulse::AnchorComponent.new(anchor_id: "anchor-button", active: true, distance: 8)) do %>
I am anchored to the button!
<% end %> ``` ### Fitting the viewport Set `auto_size` and cap the element's size with the custom property it exposes, so a tall menu scrolls instead of overflowing the viewport. When the cap squashes the element and the other side of the anchor has more room, the element flips there. ```erb <%= render(Impulse::AnchorComponent.new(anchor_id: "anchor-button", active: true, auto_size: "height", auto_size_padding: 8, class: "menu")) do %> ... <% end %> ``` ```css .menu { max-height: var(--awc-auto-size-height); overflow-y: auto; } ``` ## Imports ```js import '@ambiki/impulse-view-components/anchor'; ``` The component has no styles of its own. ## JS API [Read here](../js-api/anchor.md). --- --- url: https://ambiki.github.io/impulse_view_components/components/clipboard-copy.md --- # Clipboard copy A button that copies text to the clipboard: a value rendered by the server, or the text of another element on the page. It emits an event once the text is copied, or when it couldn't be, and enters a short feedback state you can style. It shows and announces nothing of its own: how the user is told, with a toast, an icon swap, or not at all, is up to your app. ## Usage ```erb <%= render(Impulse::ClipboardCopyComponent.new(value: "https://example.com/meetings/123", class: "btn btn-primary")) do %> Copy link <% end %> ``` The component renders ``, which is the button itself. It is announced as a button, takes focus, and is pressed with a click, Enter, or Space, like a native `