maquina-components 0.4.4 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5347ee9b9b49584bdb8549ecc263f2137ce2331b805c5539cab9db84babf9f14
-  data.tar.gz: 18b6b97ab09e7f5506c0d539db940808e48c481893ce6ad933f5226fbbd1dae9
+  metadata.gz: 9159362a034d89b9abf1b6a5a636851942f69c32491eea74c438c9d8dc678b57
+  data.tar.gz: 9ab23823a833fdfb8d02727fea268539ea0dd26d974b3212aedf90c87d2c5963
 SHA512:
-  metadata.gz: bcbde28da68d8b05b3d97d47f2f373cb7313f37265d26b78ed309827011c1cf7e1d1871d68ec6b9670240b73b1464979a0af37faa4d495e15c5b7f40ecc1a3ca
-  data.tar.gz: 47eb6037d5e98fc4b913750239d2e420c28c69b128ea4c5b9b17a450a5a2b5163f36e16cf7892b514e0c02622773c67e6620e90eea3e25d1f6350525b1a234d3
+  metadata.gz: 2b7d4230c490e4a98db049a2a527300b060873b6befb6925c2825455923e2179f353ffadbca0f90ebda98779ef711083b819c60a13763a5d982be3d22b73ab4e
+  data.tar.gz: c0671e469d43f1fbc265638755f453365748f2cf3d39e435ffa5218d81f9453a55f87cd1babe8acdfb2ccfdfb21a4e2415366a82388ddabb74f9a127a3bdc821

data/README.md

@@ -76,6 +76,8 @@ This will:
 - Add theme variables (light + dark mode)
 - Create a helper file for icon customization
 
+All engine helpers (`icon_for`, `sidebar_open?`, `toast_flash_messages`, etc.) are automatically available in your views without any additional configuration.
+
 ### 3. Use Components
 
 ```erb
@@ -117,6 +119,19 @@ bin/rails generate maquina_components:install --skip-theme
 bin/rails generate maquina_components:install --skip-helper
 ```
 
+### Scaffold Templates
+
+Copy ERB scaffold templates into your application so Rails' built-in `scaffold`
+generator produces maquina_components-styled views:
+
+```bash
+bin/rails generate maquina_components:scaffold_templates
+```
+
+This installs `index`, `show`, `new`, `edit`, `_form`, and partial templates to
+`lib/templates/erb/scaffold/`. After running it, `rails generate scaffold ModelName field:type`
+generates views built with maquina_components. Customize the templates as needed.
+
 **Prerequisite:** [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) must be installed first.
 
 ---
@@ -137,8 +152,10 @@ bin/rails generate maquina_components:install --skip-helper
 | **Card** | Content container with header, content, footer | [Card](https://maquina.app/documentation/components/card/) |
 | **Alert** | Callout messages (info, warning, error) | [Alert](https://maquina.app/documentation/components/alert/) |
 | **Badge** | Status indicators and labels | [Badge](https://maquina.app/documentation/components/badge/) |
-| **Table** | Data tables with sorting support | [Table](https://maquina.app/documentation/components/table/) |
+| **Table** | Data tables with striped and bordered variants | [Table](https://maquina.app/documentation/components/table/) |
+| **Separator** | Horizontal or vertical divider | [Separator](https://maquina.app/documentation/components/separator/) |
 | **Empty State** | Placeholder for empty lists | [Empty State](https://maquina.app/documentation/components/empty/) |
+| **Stats** | Metric cards in a responsive grid | [Stats](https://maquina.app/documentation/components/stats/) |
 
 ### Navigation Components
 
@@ -155,6 +172,7 @@ bin/rails generate maquina_components:install --skip-helper
 | **Calendar** | Inline date picker with single/range selection | [Calendar](https://maquina.app/documentation/components/calendar/) |
 | **Combobox** | Searchable dropdown with keyboard navigation | [Combobox](https://maquina.app/documentation/components/combobox/) |
 | **Date Picker** | Popover-based date selection | [Date Picker](https://maquina.app/documentation/components/date-picker/) |
+| **Drawer** | Slide-out panel with overlay and keyboard shortcut | [Drawer](https://maquina.app/documentation/components/drawer/) |
 | **Toggle Group** | Single/multiple selection button group | [Toggle Group](https://maquina.app/documentation/components/toggle-group/) |
 
 ### Feedback Components

data/app/assets/stylesheets/breadcrumbs.css

@@ -94,6 +94,7 @@
 [data-breadcrumb-part="ellipsis"] {
   @apply inline-flex size-9 items-center justify-center;
   color: var(--muted-foreground);
+  cursor: pointer;
 }
 
 [data-breadcrumb-part="ellipsis"] svg {
@@ -106,6 +107,26 @@
   color: var(--foreground);
 }
 
+/* ===== Overflow Dropdown (top-layer popover) ===== */
+/* Visual styling comes from dropdown_menu.css via data-dropdown-menu-part.
+   Anchor positioning places the popover in modern browsers;
+   breadcrumb_controller falls back to measured coordinates elsewhere.
+   The doubled attribute selector outranks dropdown_menu.css's
+   position: absolute regardless of import order. */
+@supports (anchor-name: --a) and (position-area: block-end) {
+  [data-breadcrumb-part="ellipsis"] {
+    anchor-name: --maquina-breadcrumbs;
+  }
+
+  [data-breadcrumb-part="dropdown"][data-dropdown-menu-part="content"] {
+    position: fixed;
+    position-anchor: --maquina-breadcrumbs;
+    position-area: block-end span-inline-end;
+    margin-block-start: 4px;
+    position-try-fallbacks: flip-block;
+  }
+}
+
 /* ===== Responsive Behavior ===== */
 /* Force nowrap when responsive controller is active so scrollWidth detects overflow */
 [data-controller="breadcrumb"] [data-breadcrumb-part="list"] {

data/app/assets/stylesheets/combobox.css

@@ -53,12 +53,47 @@
   @apply rounded-md border p-0 shadow-md outline-none;
   @apply min-w-[200px];
 
-  /* Reset popover defaults - positioning handled by JS */
+  /* Reset popover defaults - positioning below (anchor CSS) or in JS fallback */
   margin: 0;
   padding: 0;
   inset: unset;
 }
 
+/* ===== Anchor Positioning (modern browsers) ===== */
+/* Places the top-layer popover declaratively; combobox_controller skips its
+   measured fallback when these features are supported. flip-block flips the
+   popover above the trigger when there is no room below — something the JS
+   fallback never did. */
+@supports (anchor-name: --a) and (position-area: block-end) {
+  [data-combobox-part="trigger"] {
+    anchor-name: --maquina-combobox;
+  }
+
+  [data-combobox-part="content"] {
+    position: fixed;
+    position-anchor: --maquina-combobox;
+    margin-block-start: 4px;
+    position-try-fallbacks: flip-block;
+  }
+
+  [data-combobox-part="content"][data-align="start"] {
+    position-area: block-end span-inline-end;
+  }
+
+  [data-combobox-part="content"][data-align="center"] {
+    position-area: block-end;
+  }
+
+  [data-combobox-part="content"][data-align="end"] {
+    position-area: block-end span-inline-start;
+  }
+
+  [data-combobox-part="content"][data-width="default"] {
+    width: auto;
+    min-width: max(200px, anchor-size(inline));
+  }
+}
+
 /* Width variants */
 [data-combobox-part="content"][data-width="sm"] {
   @apply w-40;

data/app/assets/stylesheets/drawer.css

@@ -0,0 +1,135 @@
+/* ===== Drawer Component Styles ===== */
+
+/* ===== Provider (Wrapper) ===== */
+[data-component="drawer"] {
+  @apply flex w-full;
+}
+
+/* ===== Drawer Root ===== */
+[data-drawer-part="root"] {
+  @apply block text-foreground;
+}
+
+/* Prevent transitions on initial load */
+[data-drawer-part="root"].drawer-loading,
+[data-drawer-part="root"].drawer-loading * {
+  transition: none !important;
+}
+
+/* ===== Drawer Backdrop (overlay) ===== */
+[data-drawer-part="backdrop"] {
+  @apply fixed inset-0 z-40 hidden bg-black opacity-0;
+  transition: opacity 300ms;
+}
+
+[data-drawer-part="backdrop"][data-state="visible"] {
+  @apply block opacity-60;
+}
+
+/* ===== Drawer Panel (fixed positioned) ===== */
+[data-drawer-part="panel"] {
+  @apply fixed inset-y-0 z-50 flex h-full w-80 flex-col;
+  @apply bg-background shadow-lg;
+  transition: right 300ms ease-in-out, left 300ms ease-in-out;
+}
+
+[data-drawer-part="root"][data-side="left"] [data-drawer-part="panel"] {
+  @apply left-0;
+  right: auto;
+}
+
+[data-drawer-part="root"][data-side="right"] [data-drawer-part="panel"] {
+  @apply right-0;
+  left: auto;
+}
+
+/* Closed state - slide out */
+[data-drawer-part="root"][data-side="left"][data-state="closed"] [data-drawer-part="panel"] {
+  @apply -translate-x-full;
+}
+
+[data-drawer-part="root"][data-side="right"][data-state="closed"] [data-drawer-part="panel"] {
+  @apply translate-x-full;
+}
+
+/* ===== Drawer Inner Content Wrapper ===== */
+[data-drawer-part="inner"] {
+  @apply flex h-full w-full flex-col;
+}
+
+/* ===== Body Scroll Lock ===== */
+/* Shared by drawer_controller and sidebar_controller: the controllers set
+   the data attribute and the --maquina-scroll-lock-top offset on <body>;
+   all styling lives here. */
+body[data-maquina-scroll-locked] {
+  position: fixed;
+  top: var(--maquina-scroll-lock-top, 0px);
+  width: 100%;
+  overflow: hidden;
+}
+
+/* ===== Drawer Header ===== */
+[data-drawer-part="header"] {
+  @apply flex shrink-0 items-center justify-between gap-2 border-b px-4 py-3;
+  border-color: var(--border);
+}
+
+[data-drawer-part="header-content"] {
+  @apply flex-1;
+}
+
+/* ===== Drawer Content (scrollable area) ===== */
+[data-drawer-part="content"] {
+  @apply flex min-h-0 flex-1 flex-col gap-2 overflow-auto p-4;
+}
+
+/* ===== Drawer Footer ===== */
+[data-drawer-part="footer"] {
+  @apply flex shrink-0 flex-col gap-2 border-t p-4;
+  border-color: var(--border);
+}
+
+/* ===== Drawer Trigger ===== */
+
+[data-drawer-part="trigger"]:hover {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+/* ===== Drawer Title ===== */
+[data-drawer-part="title"] {
+  @apply text-lg font-semibold;
+}
+
+/* ===== Drawer Description ===== */
+[data-drawer-part="description"] {
+  @apply text-sm text-muted-foreground;
+}
+
+/* ===== Drawer Close Button ===== */
+[data-drawer-part="close"] {
+  @apply inline-flex items-center justify-center rounded-md p-1;
+  @apply outline-hidden ring-ring focus-visible:ring-2;
+  @apply transition-colors;
+  color: var(--foreground);
+}
+
+[data-drawer-part="close"]:hover {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+[data-drawer-part="close"] svg {
+  @apply size-4;
+}
+
+/* ===== Drawer Section ===== */
+[data-drawer-part="section"] {
+  @apply flex flex-col gap-2;
+}
+
+/* ===== Drawer Separator ===== */
+[data-drawer-part="separator"] {
+  @apply mx-4 my-2 w-auto;
+  background-color: var(--border);
+}

data/app/assets/stylesheets/menu_button.css

@@ -0,0 +1,155 @@
+/* ===== Menu Button Component Styles ===== */
+/*
+ * Sidebar-flavored button that opens a dropdown panel.
+ * Pairs _menu_button.html.erb (trigger) with _dropdown.html.erb (content)
+ * and menu_button_controller.js.
+ *
+ * Structure:
+ * - menu-button (root ul)
+ *   - item (li with Stimulus controller)
+ *     - trigger (button)
+ *       - avatar (text icon square)
+ *       - text (title + subtitle)
+ *     - content (positioned dropdown panel)
+ */
+
+/* ===== Root Container ===== */
+[data-component="menu-button"] {
+  @apply flex w-full min-w-0 flex-col gap-1;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+[data-menu-button-part="item"] {
+  position: relative;
+  list-style: none;
+}
+
+/* ===== Trigger Button ===== */
+[data-menu-button-part="trigger"] {
+  @apply flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm;
+  @apply transition-[width,height,padding] duration-150;
+  height: 3rem;
+  background-color: transparent;
+  color: inherit;
+  border: none;
+  outline: none;
+  cursor: pointer;
+}
+
+[data-menu-button-part="trigger"]:hover,
+[data-menu-button-part="trigger"]:active,
+[data-menu-button-part="trigger"][data-state="open"] {
+  background-color: var(--sidebar-accent);
+  color: var(--sidebar-accent-foreground);
+}
+
+[data-menu-button-part="trigger"]:focus-visible {
+  box-shadow: 0 0 0 2px var(--sidebar-ring);
+}
+
+[data-menu-button-part="trigger"]:disabled,
+[data-menu-button-part="trigger"][aria-disabled="true"] {
+  pointer-events: none;
+  opacity: 0.5;
+}
+
+[data-menu-button-part="trigger"] svg {
+  @apply size-4 shrink-0;
+}
+
+[data-menu-button-part="trigger"] img {
+  @apply shrink-0;
+}
+
+/* Icon-collapsed sidebar squeezes the trigger to an icon square */
+[data-sidebar-part="root"][data-collapsible="icon"] [data-menu-button-part="trigger"] {
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+}
+
+/* ===== Avatar (text icon) ===== */
+[data-menu-button-part="avatar"] {
+  @apply flex aspect-square size-8 shrink-0 items-center justify-center rounded-lg;
+  background-color: var(--sidebar-primary);
+  color: var(--sidebar-primary-foreground);
+}
+
+/* ===== Text (title + subtitle) ===== */
+[data-menu-button-part="text"] {
+  @apply grid flex-1 text-left text-sm leading-tight;
+}
+
+[data-menu-button-part="title"] {
+  @apply truncate font-semibold;
+}
+
+[data-menu-button-part="subtitle"] {
+  @apply truncate text-xs;
+}
+
+/* ===== Content Panel ===== */
+[data-menu-button-part="content"] {
+  position: absolute;
+  z-index: 50;
+  display: none;
+  flex-direction: column;
+  overflow: hidden;
+  min-width: 14rem;
+  max-width: 14rem;
+  background-color: var(--popover, var(--background));
+  color: var(--popover-foreground, var(--foreground));
+  @apply rounded-lg border p-1 shadow-md;
+  border-color: var(--border);
+}
+
+[data-menu-button-part="content"][data-side="top"] {
+  bottom: calc(100% + 4px);
+}
+
+[data-menu-button-part="content"][data-side="bottom"] {
+  top: calc(100% + 4px);
+}
+
+[data-menu-button-part="content"][data-align="start"] {
+  left: 0;
+}
+
+[data-menu-button-part="content"][data-align="end"] {
+  right: 0;
+}
+
+/* Animation states */
+[data-menu-button-part="content"][data-state="open"] {
+  display: flex;
+  animation: menu-button-in 150ms ease-out;
+}
+
+[data-menu-button-part="content"][data-state="closing"] {
+  display: flex;
+  animation: menu-button-out 100ms ease-in forwards;
+}
+
+@keyframes menu-button-in {
+  from {
+    opacity: 0;
+    transform: scale(0.95) translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
+@keyframes menu-button-out {
+  from {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: scale(0.95) translateY(4px);
+  }
+}

data/app/assets/stylesheets/separator.css

@@ -0,0 +1,20 @@
+/* ===== Separator Component Styles ===== */
+/*
+ * Decorative divider, horizontal or vertical.
+ * Styled via data attributes; colors come from theme variables.
+ */
+
+[data-component="separator"] {
+  @apply mx-2 shrink-0;
+  background-color: var(--border);
+}
+
+[data-component="separator"][data-orientation="horizontal"] {
+  height: 1px;
+  width: 100%;
+}
+
+[data-component="separator"][data-orientation="vertical"] {
+  width: 1px;
+  height: 1rem;
+}

data/app/assets/stylesheets/sidebar.css

@@ -290,6 +290,18 @@
   @apply truncate;
 }
 
+[data-sidebar-part="menu-link-text"] {
+  @apply flex flex-col gap-0.5 leading-none;
+}
+
+[data-sidebar-part="menu-link-title"] {
+  @apply font-medium;
+}
+
+[data-sidebar-part="menu-link-subtitle"] {
+  @apply text-xs text-sidebar-foreground/70;
+}
+
 /* Has menu action - add padding */
 .group-has-data-\[sidebar-part\=menu-action\]\/menu-item [data-sidebar-part="menu-link"],
 [data-sidebar-part="menu-item"]:has([data-sidebar-part="menu-action"]) [data-sidebar-part="menu-link"] {

data/app/assets/stylesheets/stats.css

@@ -0,0 +1,101 @@
+/* ===== Stats Component Styles ===== */
+/*
+ * Dashboard stat cards and their responsive grid.
+ *
+ * Structure:
+ * - stats-grid (root, optional action slot)
+ *   - action (leading or trailing action area)
+ *   - grid (responsive card grid, columns via data-columns)
+ * - stats-card
+ *   - body
+ *     - text (title, value, subtitle)
+ *     - icon
+ */
+
+/* ===== Card ===== */
+[data-component="stats-card"] {
+  @apply rounded-lg border p-4 shadow-sm;
+  background-color: var(--card);
+  border-color: var(--border);
+}
+
+[data-component="stats-card"] [data-stats-part="body"] {
+  @apply flex items-center justify-between;
+}
+
+[data-component="stats-card"] [data-stats-part="title"] {
+  @apply text-sm;
+  color: var(--muted-foreground);
+}
+
+[data-component="stats-card"] [data-stats-part="value"] {
+  @apply text-2xl font-bold;
+}
+
+[data-component="stats-card"] [data-stats-part="subtitle"] {
+  @apply mt-1 text-xs;
+  color: var(--muted-foreground);
+}
+
+[data-component="stats-card"] [data-stats-part="icon"] svg {
+  @apply size-8 shrink-0;
+}
+
+/* Color defaults live in the components layer so caller utility classes
+   (value_classes / icon_classes, e.g. text-green-600) always win — the
+   utilities layer is defined to beat the components layer, and unlayered
+   rules would beat utilities regardless of specificity */
+@layer components {
+  [data-component="stats-card"] [data-stats-part="value"] {
+    color: var(--foreground);
+  }
+
+  [data-component="stats-card"] [data-stats-part="icon"] {
+    color: var(--muted-foreground);
+  }
+}
+
+/* ===== Grid ===== */
+[data-component="stats-grid"][data-with-action="true"] {
+  @apply flex flex-col gap-4 lg:flex-row lg:items-center;
+}
+
+[data-component="stats-grid"] [data-stats-part="grid"] {
+  @apply grid grid-cols-1 gap-4;
+}
+
+[data-component="stats-grid"][data-with-action="true"] [data-stats-part="grid"] {
+  @apply flex-1;
+}
+
+[data-component="stats-grid"][data-columns="2"] [data-stats-part="grid"] {
+  @apply sm:grid-cols-2;
+}
+
+[data-component="stats-grid"][data-columns="3"] [data-stats-part="grid"] {
+  @apply sm:grid-cols-3;
+}
+
+[data-component="stats-grid"][data-columns="4"] [data-stats-part="grid"] {
+  @apply sm:grid-cols-4;
+}
+
+[data-component="stats-grid"][data-columns="5"] [data-stats-part="grid"] {
+  @apply sm:grid-cols-5;
+}
+
+[data-component="stats-grid"][data-columns="6"] [data-stats-part="grid"] {
+  @apply sm:grid-cols-6;
+}
+
+[data-component="stats-grid"] [data-stats-part="action"] {
+  @apply flex justify-center;
+}
+
+[data-component="stats-grid"] [data-stats-part="action"][data-position="start"] {
+  @apply lg:justify-start;
+}
+
+[data-component="stats-grid"] [data-stats-part="action"][data-position="end"] {
+  @apply lg:justify-end;
+}

data/app/assets/tailwind/maquina_components_engine/engine.css

@@ -7,12 +7,16 @@
 @import "../../stylesheets/card.css";
 @import "../../stylesheets/combobox.css";
 @import "../../stylesheets/date_picker.css";
+@import "../../stylesheets/drawer.css";
 @import "../../stylesheets/dropdown_menu.css";
 @import "../../stylesheets/empty.css";
 @import "../../stylesheets/form.css";
 @import "../../stylesheets/header.css";
+@import "../../stylesheets/menu_button.css";
 @import "../../stylesheets/pagination.css";
+@import "../../stylesheets/separator.css";
 @import "../../stylesheets/sidebar.css";
+@import "../../stylesheets/stats.css";
 @import "../../stylesheets/table.css";
 @import "../../stylesheets/toast.css";
 @import "../../stylesheets/toggle_group.css";

data/app/helpers/maquina_components/combobox_helper.rb

@@ -59,7 +59,8 @@ module MaquinaComponents
     # @return [String] Rendered HTML
     def combobox(id: nil, name: nil, value: nil, placeholder: "Select...", css_classes: "", **html_options, &block)
       builder = ComboboxBuilder.new(self, placeholder: placeholder)
-      combobox_id = id || "combobox-#{SecureRandom.hex(4)}"
+      # Deterministic fallback id: random ids break idiomorph matching across Turbo morphs
+      combobox_id = id || "combobox-#{name.to_s.parameterize.presence || "default"}"
       builder.combobox_id = combobox_id
 
       capture(builder, &block)

data/app/helpers/maquina_components/components_helper.rb

@@ -0,0 +1,33 @@
+module MaquinaComponents
+  # Shared plumbing for component partials.
+  module ComponentsHelper
+    # Merges a caller's data: hash with a component's own data attributes.
+    #
+    # Component values win for identity keys (component, variant, size, ...)
+    # so callers can't accidentally break a component's styling hooks. The
+    # Stimulus token keys :controller and :action concatenate instead, so a
+    # caller can attach extra behavior without losing the component's:
+    #
+    #   <%= render "components/combobox", name: "country",
+    #         data: { controller: "analytics", action: "change->analytics#track" } %>
+    #   # => data-controller="combobox analytics"
+    #
+    # @param html_options [Hash] the partial's **html_options (data: is consumed)
+    # @param component_data [Hash] the component's own data attributes
+    # @return [Hash] the merged data hash
+    def merge_component_data(html_options, **component_data)
+      user_data = html_options.delete(:data) || {}
+      merged = user_data.merge(component_data)
+
+      [:controller, :action].each do |key|
+        user_value = user_data[key] || user_data[key.to_s]
+        next if user_value.blank? || component_data[key].blank?
+
+        merged.delete(key.to_s)
+        merged[key] = "#{component_data[key]} #{user_value}"
+      end
+
+      merged
+    end
+  end
+end

data/app/helpers/maquina_components/drawer_helper.rb

@@ -0,0 +1,19 @@
+module MaquinaComponents
+  module DrawerHelper
+    def drawer_state(cookie_name = "drawer_state")
+      cookie_value = cookies[cookie_name]
+
+      return :open if cookie_value.nil?
+
+      (cookie_value == "true") ? :open : :closed
+    end
+
+    def drawer_open?(cookie_name = "drawer_state")
+      drawer_state(cookie_name) == :open
+    end
+
+    def drawer_closed?(cookie_name = "drawer_state")
+      drawer_state(cookie_name) == :closed
+    end
+  end
+end