view_primitives 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cae6ead2a2d30db140973eb5f5a925e2845a3d6dc4caae79bbd8a461fb56eb9f
+  data.tar.gz: 5ece5bd38e0e0db26522fb29fcec2f466396b58caff8a172a41f2bdc8b14ecaa
+SHA512:
+  metadata.gz: 7175d71aa115dce9d0f34f6275b6d05a8997e41328f40809aaee7b127337f011b4323ef9a984085f01f2e9d56cfdb822c593a1bf6188028d6e9eb76658774573
+  data.tar.gz: 35a018df2effe68ffccc863056e503f12a0fd3e101f38bba557f2e42247109091d9f2b50edea55e8f1da29ea06517109619f826428a70291329d26b03fe01cc8

data/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+### Added
+
+**Generators**
+- `rails g view_primitives:install` — copies `ApplicationComponent`, CSS variables, prints Tailwind config
+- `rails g view_primitives:add <component>` — copies component files into `app/components/ui/`; warns before overwriting
+- `rails g view_primitives:list` — shows all available components with installed status
+- `ui` helper available in controllers, views, and Action Mailer views
+- Install generator checks `UI` inflection and detects existing Tailwind entry point
+
+**Phase 1 — Foundation**
+- Button — 6 variants, 4 sizes, defaults to `type="button"` inside forms
+- Alert — informational banner with title/description slots and destructive variant
+- Accordion — collapsible `<details>` sections; optional `exclusive:` Stimulus mode
+
+**Phase 2 — Display**
+- Badge, Avatar, Card, Separator, Label, Skeleton, Progress, Aspect Ratio, Spinner, KBD
+- Rating — read-only star display
+- Rating Input — interactive star rating with form/AJAX submission
+- Indicator — status dot/count badge overlaid on an element
+- List Group — bordered list with optional links and active state
+- Banner — announcement strip with variants
+- Button Group — visually joined row of buttons
+
+**Phase 3 — Forms**
+- Input, Textarea, Checkbox, Radio Group, Select, Switch, Toggle, Toggle Group
+- Form Field — label + input + hint + error layout wrapper
+- File Input, Search Input, Number Input, Range, Floating Label
+
+**Phase 4 — Navigation**
+- Tabs — array API + Stimulus slot API
+- Breadcrumb, Pagination, Stepper, Bottom Navigation, Footer
+- Navbar — responsive top bar with hamburger
+- Navigation Menu — top-level nav with dropdown flyouts
+- Mega Menu — full-width dropdown with grouped links and images
+
+**Phase 5 — Overlays**
+- Dialog, Alert Dialog, Sheet, Drawer, Popover, Tooltip, Hover Card
+
+**Phase 6 — Menus**
+- Dropdown Menu, Context Menu, Menubar, Command, Combobox
+
+**Phase 7 — Complex**
+- Calendar, Date Picker, Timepicker, Carousel, Data Table, Sidebar, Input OTP
+- Collapsible, Scroll Area, Resizable
+- Gallery — responsive image grid with optional lightbox
+- Chat Bubble, Speed Dial, Device Mockup, QR Code
+
+**Phase 8 — Advanced**
+- Chart — Chart.js adapter (bar, line, pie, doughnut, radar, polar area)
+- Toaster — stacked toast notifications (Sonner-style)
+- Timeline — vertical timeline with event items
+- WYSIWYG — rich-text editor with Trix (default) or Quill adapter
+
+**Phase 9 — Media & Semantic HTML**
+- Picture — `<picture>` + `<source>` for art direction and modern formats (AVIF/WebP)
+- Video — `<video>` + `<source>` with poster, controls, and `<track>` captions
+- Figure — `<figure>` + `<figcaption>` wrapper
+- Image — responsive `<img>` with `srcset` / `sizes`
+- Audio — `<audio>` + `<source>` with optional transcript link
+- Iframe — sandboxed embed wrapper with required `title` and lazy loading
+- Map / Area — image map with clickable `<area>` regions
+- Embed — third-party embeds with automatic provider detection from URL; supports YouTube, Vimeo, Spotify, Google Maps, Yandex Maps, Loom, SoundCloud, X (Twitter), Telegram, Facebook
+
+### Changed
+
+- Removed public `component` helper — use `ui` for primitives, `render` for other namespaces
+- `AddGenerator` copies files from template directories automatically (no per-component methods)
+- `Components.supported` is derived from template directories, not a duplicated list
+- Simplified `Detector` and `ComponentHelper`
+- `view_primitives:add` exits with status 1 on unknown components; prints copy summary
+- Requires `view_component >= 4.0` and Rails `>= 7.1`
+
+[0.1.0]: https://github.com/alec-c4/view_primitives/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Poimtsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,198 @@
+# ViewPrimitives
+
+A [shadcn/ui](https://ui.shadcn.com)-inspired component library for Rails built on [ViewComponent](https://viewcomponent.org).
+
+> **Acknowledgements** — The visual design, CSS class choices, and component structure of ViewPrimitives are heavily inspired by [shadcn/ui](https://ui.shadcn.com) and its Svelte port [shadcn-svelte](https://www.shadcn-svelte.com). We are grateful to [@shadcn](https://github.com/shadcn) and all contributors for their outstanding open-source work. ViewPrimitives is an independent Rails adaptation and is not affiliated with or endorsed by the shadcn/ui project.
+
+Components are **copied into your app** via a generator — not imported from a package. Tailwind classes live in your own files, so any Tailwind setup works out of the box: `tailwindcss-rails`, `cssbundling-rails`, Vite, esbuild — no configuration required.
+
+## Requirements
+
+- Ruby >= 3.2 (developed with 4.0.5 — use [mise](https://mise.jdx.dev) or see `.ruby-version`)
+- Rails >= 7.1 (required by ViewComponent 4)
+- [ViewComponent](https://viewcomponent.org) >= 4.0
+- [Tailwind CSS](https://tailwindcss.com) (any setup)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "view_primitives"
+```
+
+Then run the install generator:
+
+```bash
+rails g view_primitives:install
+```
+
+This will:
+- Create `app/components/application_component.rb` with `ViewPrimitives::ClassHelper` included (skipped if you already have one — add `include ViewPrimitives::ClassHelper` manually)
+- Create `app/assets/stylesheets/view_primitives.css` with the design token definitions (`@theme inline` + oklch light/dark theme)
+
+Then import it in your Tailwind CSS entry point:
+
+```css
+/* tailwindcss-rails  → app/assets/tailwind/application.css              */
+/* tailwind (legacy)  → app/assets/stylesheets/application.tailwind.css  */
+/* cssbundling/Vite   → app/javascript/application.css                    */
+
+@import "./view_primitives";
+```
+
+The install generator auto-detects these entry points and injects the import when possible.
+
+### UI namespace
+
+Components live under `UI::` (files in `app/components/ui/`). The gem registers the `UI` acronym with ActiveSupport so `ui :button` resolves to `UI::ButtonComponent`.
+
+That's it — no `tailwind.config.js` required. Tailwind 4 reads the `@theme inline` block directly from the CSS.
+
+## Adding components
+
+```bash
+rails g view_primitives:list                         # available + installed status
+rails g view_primitives:add button
+rails g view_primitives:add button alert accordion   # multiple at once
+```
+
+Each component is copied into `app/components/ui/` as plain Ruby and ERB files you own and can modify freely. Re-running `add` overwrites existing files (a warning is printed). Unknown component names fail with a non-zero exit code.
+
+## View helpers
+
+ViewPrimitives adds the `ui` helper to views and mailers:
+
+```erb
+<%# Positional label — no block needed %>
+<%= ui :button, "Save changes", variant: :outline %>
+<%= ui :alert, title: "Heads up!", description: "Check your settings." %>
+<%= ui :accordion, items: [{ title: "FAQ", content: "Answer here." }] %>
+
+<%# Block — for icons, slots, or complex content %>
+<%= ui :button do %><svg .../> Save<% end %>
+<%= ui :alert do |a| %><% a.with_alert_title { "Note" } %><% end %>
+```
+
+`ui` is shorthand for `render UI::SomeComponent.new(...)`. For components outside `app/components/ui/`, use `render` as usual.
+
+## Components
+
+### Available now
+
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Button | Clickable element with 6 variants and 4 sizes | [docs](docs/components/button.md) |
+| Alert | Informational banner with title and description slots | [docs](docs/components/alert.md) |
+| Accordion | Collapsible sections via native `<details>`, optional exclusive mode | [docs](docs/components/accordion.md) |
+| Badge | Small status label with variants | [docs](docs/components/badge.md) |
+| Avatar | User avatar with image and initials fallback | [docs](docs/components/avatar.md) |
+| Card | Container with header, content, and footer slots | [docs](docs/components/card.md) |
+| Separator | Horizontal or vertical divider | [docs](docs/components/separator.md) |
+| Label | Accessible form label | [docs](docs/components/label.md) |
+| Skeleton | Loading placeholder with pulse animation | [docs](docs/components/skeleton.md) |
+| Progress | Progress bar with value prop | [docs](docs/components/progress.md) |
+| Aspect Ratio | Constrains child content to a given aspect ratio | [docs](docs/components/aspect_ratio.md) |
+| Spinner | Animated loading indicator | [docs](docs/components/spinner.md) |
+| KBD | Keyboard shortcut key display | [docs](docs/components/kbd.md) |
+| Rating | Read-only star rating display | [docs](docs/components/rating.md) |
+| Rating Input | Interactive star rating — form or AJAX submission | [docs](docs/components/rating_input.md) |
+| Indicator | Status dot or count badge overlaid on an element | [docs](docs/components/indicator.md) |
+| List Group | Bordered list with optional links and active state | [docs](docs/components/list_group.md) |
+| Banner | Styled announcement strip with variants | [docs](docs/components/banner.md) |
+| Button Group | Visually joined row of buttons | [docs](docs/components/button_group.md) |
+| Input | Styled text input with ring/border | [docs](docs/components/input.md) |
+| Textarea | Styled multi-line input | [docs](docs/components/textarea.md) |
+| Checkbox | Accessible checkbox with optional label | [docs](docs/components/checkbox.md) |
+| Radio Group | Group of radio inputs | [docs](docs/components/radio_group.md) |
+| Select | Native styled select element | [docs](docs/components/select.md) |
+| Switch | CSS-only on/off toggle | [docs](docs/components/switch.md) |
+| Toggle | Single pressable toggle button | [docs](docs/components/toggle.md) |
+| Toggle Group | Group of related toggles (single or multiple) | [docs](docs/components/toggle_group.md) |
+| Form Field | Label + input + hint + error layout wrapper | [docs](docs/components/form_field.md) |
+| File Input | Styled file upload input | [docs](docs/components/file_input.md) |
+| Search Input | Text input with built-in search icon and clear button | [docs](docs/components/search_input.md) |
+| Number Input | Text input with increment/decrement controls | [docs](docs/components/number_input.md) |
+| Range | Styled range slider | [docs](docs/components/range.md) |
+| Floating Label | Input with floating placeholder label | [docs](docs/components/floating_label.md) |
+| Breadcrumb | Navigational breadcrumb trail with separator | [docs](docs/components/breadcrumb.md) |
+| Pagination | Page number links with prev/next and ellipsis | [docs](docs/components/pagination.md) |
+| Stepper | Multi-step progress indicator (horizontal + vertical) | [docs](docs/components/stepper.md) |
+| Tabs | Tab bar with content panels (array API + slot API) | [docs](docs/components/tabs.md) |
+| Navbar | Responsive top navigation bar with hamburger menu | [docs](docs/components/navbar.md) |
+| Navigation Menu | Top-level navigation with optional dropdown flyouts | [docs](docs/components/navigation_menu.md) |
+| Bottom Nav | Mobile-style tab bar fixed to the bottom | [docs](docs/components/bottom_nav.md) |
+| Footer | Page footer with columns, links, and copyright | [docs](docs/components/footer.md) |
+| Mega Menu | Full-width dropdown panel with grouped links and images | [docs](docs/components/mega_menu.md) |
+| Dialog | Modal dialog with trigger, title, description, footer slots | [docs](docs/components/dialog.md) |
+| Alert Dialog | Blocking confirmation dialog | [docs](docs/components/alert_dialog.md) |
+| Sheet | Slide-in panel from any edge (left/right/top/bottom) | [docs](docs/components/sheet.md) |
+| Drawer | Bottom sheet with drag handle — mobile drawer pattern | [docs](docs/components/drawer.md) |
+| Popover | Floating panel anchored to a trigger | [docs](docs/components/popover.md) |
+| Tooltip | Hover label — CSS-only, no JS | [docs](docs/components/tooltip.md) |
+| Hover Card | Rich hover preview card — CSS-only, no JS | [docs](docs/components/hover_card.md) |
+| Dropdown Menu | Trigger-anchored menu with items and separators | [docs](docs/components/dropdown_menu.md) |
+| Context Menu | Right-click context menu positioned at cursor | [docs](docs/components/context_menu.md) |
+| Menubar | Horizontal application-style menu bar | [docs](docs/components/menubar.md) |
+| Command | Modal command palette with live search filtering | [docs](docs/components/command.md) |
+| Combobox | Autocomplete select with live search | [docs](docs/components/combobox.md) |
+| Calendar | Date picker calendar grid | [docs](docs/components/calendar.md) |
+| Date Picker | Input that opens a Calendar popover | [docs](docs/components/date_picker.md) |
+| Timepicker | Input for selecting a time value | [docs](docs/components/timepicker.md) |
+| Carousel | Scrollable item carousel with prev/next controls | [docs](docs/components/carousel.md) |
+| Data Table | Sortable, filterable table with pagination | [docs](docs/components/data_table.md) |
+| Sidebar | Collapsible application sidebar with nav groups | [docs](docs/components/sidebar.md) |
+| Input OTP | One-time-password digit input group | [docs](docs/components/input_otp.md) |
+| Collapsible | Single collapsible section (simpler than Accordion) | [docs](docs/components/collapsible.md) |
+| Resizable | Drag-to-resize panel layout | [docs](docs/components/resizable.md) |
+| Scroll Area | Custom scrollbar container | [docs](docs/components/scroll_area.md) |
+| Gallery | Responsive image grid with optional lightbox | [docs](docs/components/gallery.md) |
+| Chat Bubble | Styled message bubble for chat or comment threads | [docs](docs/components/chat_bubble.md) |
+| Speed Dial | Floating action button that expands into sub-actions | [docs](docs/components/speed_dial.md) |
+| Device Mockup | Phone or browser frame for marketing screenshots | [docs](docs/components/device_mockup.md) |
+| QR Code | QR code display from a given value | [docs](docs/components/qr_code.md) |
+| Timeline | Vertical timeline with event items | [docs](docs/components/timeline.md) |
+| Toaster | Stacked toast notifications (Sonner-style) | [docs](docs/components/toaster.md) |
+| Chart | Chart.js adapter — bar, line, pie, doughnut, radar, polar area | [docs](docs/components/chart.md) |
+| Picture | `<picture>` + `<source>` for art direction and modern formats (AVIF/WebP) | [docs](docs/components/picture.md) |
+| Video | `<video>` + `<source>` with poster, controls, and caption tracks | [docs](docs/components/video.md) |
+| Figure | `<figure>` + `<figcaption>` wrapper for media content | [docs](docs/components/figure.md) |
+| Image | Responsive `<img>` with `srcset` / `sizes` | [docs](docs/components/image.md) |
+| Audio | `<audio>` + `<source>` with optional transcript link | [docs](docs/components/audio.md) |
+| Iframe | Sandboxed embed wrapper with required `title` and lazy loading | [docs](docs/components/iframe.md) |
+| WYSIWYG | Rich-text editor — Trix (default) or Quill adapter | [docs](docs/components/wysiwyg.md) |
+| Map / Area | Image map with clickable `<area>` regions | [docs](docs/components/map_area.md) |
+| Embed | Third-party embeds — YouTube, Vimeo, Spotify, Google Maps, Yandex Maps, Loom, SoundCloud, X, Telegram, Facebook | [docs](docs/components/embed.md) |
+
+See [ROADMAP.md](ROADMAP.md) for the full component list organised by phase.
+
+## Customisation
+
+See **[docs/customization.md](docs/customization.md)** for the full guide covering:
+
+- Design tokens (OKLCH colors, radius) — change the whole palette in one file
+- Editing component constants — add variants, change classes
+- Per-instance `class:` overrides — append utilities without touching the file
+- Full brand theming example
+
+## Development
+
+```bash
+bin/setup          # install dependencies
+bundle exec rake   # run tests + linter
+bin/console        # interactive prompt
+```
+
+To run tests against a specific Rails version:
+
+```bash
+bundle exec appraisal rails-8.1 rake test
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alec-c4/view_primitives.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/view_primitives/add/add_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "../components"
+require_relative "../detector"
+
+module ViewPrimitives
+  module Generators
+    class AddGenerator < Rails::Generators::Base
+      include Detector
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :components, type: :array
+
+      def copy_components
+        @copied = []
+        @unknown = []
+
+        components.each do |name|
+          if Components.supported.include?(name)
+            copy_component(name)
+            @copied << name
+          else
+            @unknown << name
+            say "  Unknown component: #{name}. Supported: #{Components.supported.join(", ")}", :red
+          end
+        end
+      end
+
+      def report_summary
+        say "" if @copied&.any? || @unknown&.any?
+        say "  Copied: #{@copied.join(", ")}", :green if @copied&.any?
+        return if @unknown.blank?
+
+        say "  Failed: #{@unknown.join(", ")} (unknown)", :red
+        say "  Run `rails g view_primitives:list` to see all available components.", :cyan
+        abort
+      end
+
+      def report_setup_notes
+        @copied&.each do |name|
+          note = Components::SETUP_NOTES[name]
+          next unless note
+
+          say ""
+          say "  ── Setup required for #{name} ──────────────────────────", :yellow
+          note.each_line { |line| say "  #{line.chomp}", :cyan }
+          say ""
+        end
+      end
+
+      def template(source, *args, **options, &block)
+        destination = args.first || options[:to]
+        warn_overwrite(destination) if destination
+        super
+      end
+
+      def copy_file(source, *args, **options)
+        destination = args.first || options[:to]
+        warn_overwrite(destination) if destination
+        super
+      end
+
+      private
+
+      def copy_component(name)
+        dir = File.join(source_root, name)
+        Dir.each_child(dir).sort.each { |file| copy_template_file(name, file) }
+        copy_extra_stimulus(name)
+      end
+
+      def copy_template_file(component, file)
+        source = "#{component}/#{file}"
+
+        case file
+        when /\.rb\.tt\z/
+          template source, "app/components/ui/#{file.delete_suffix(".tt")}"
+        when /\.html\.erb\z/
+          copy_file source, "app/components/ui/#{file}"
+        when /_controller\.js\z/
+          copy_js_controller source, file.delete_suffix("_controller.js")
+        end
+      end
+
+      def copy_extra_stimulus(name)
+        config = Components::EXTRA_STIMULUS[name]
+        copy_js_controller(config[:source], config[:name]) if config
+      end
+
+      def copy_js_controller(source, stimulus_name)
+        dir = js_controllers_dir
+        unless dir
+          say "  Could not detect a JS controllers directory.", :yellow
+          say "  Copy #{source} manually and register Stimulus `#{stimulus_name}`.", :cyan
+          return
+        end
+
+        dest = "#{dir}/#{stimulus_name}_controller.js"
+        copy_file source, dest
+        say "  Stimulus `#{stimulus_name}` → #{dest}", :green
+      end
+
+      def warn_overwrite(destination)
+        return unless File.exist?(File.join(destination_root, destination))
+
+        say "  #{destination} already exists — overwriting.", :yellow
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/accordion/accordion_component.html.erb

@@ -0,0 +1,10 @@
+<%= tag.div(class: "w-full", **wrapper_attrs) do %>
+  <% @items_data.each do |item| %>
+    <%= render UI::AccordionItemComponent.new(title: item[:title], open: item.fetch(:open, false)) do %>
+      <%= item[:content] %>
+    <% end %>
+  <% end %>
+  <% items.each do |item| %>
+    <%= item %>
+  <% end %>
+<% end %>

data/lib/generators/view_primitives/add/templates/accordion/accordion_component.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module UI
+  class AccordionComponent < ApplicationComponent
+    renders_many :items, "UI::AccordionItemComponent"
+
+    # items:     array shorthand — each entry: { title:, content:, open: (optional) }
+    # exclusive: when true, opening one item closes all others via Stimulus
+    def initialize(items: nil, exclusive: false)
+      @items_data = Array(items)
+      @exclusive = exclusive
+    end
+
+    private
+
+    def wrapper_attrs
+      return {} unless @exclusive
+
+      { data: { controller: "accordion", action: "click->accordion#toggle" } }
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/accordion/accordion_controller.js

@@ -0,0 +1,15 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  toggle(event) {
+    const summary = event.target.closest("summary")
+    if (!summary) return
+
+    const target = summary.closest("details")
+    if (!target || target.open) return
+
+    this.element.querySelectorAll("details[open]").forEach(item => {
+      if (item !== target) item.open = false
+    })
+  }
+}

data/lib/generators/view_primitives/add/templates/accordion/accordion_item_component.rb.tt

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module UI
+  class AccordionItemComponent < ApplicationComponent
+    SUMMARY_CLASSES = "flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium " \
+                      "transition-all outline-none hover:underline cursor-pointer list-none " \
+                      "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 " \
+                      "disabled:pointer-events-none disabled:opacity-50"
+
+    def initialize(title:, open: false, **html_attrs)
+      @title = title
+      @open = open
+      @extra_class = html_attrs.delete(:class)
+      @html_attrs = html_attrs
+    end
+
+    def call
+      content_tag(:details, details_content, **details_attrs)
+    end
+
+    private
+
+    def details_attrs
+      attrs = @html_attrs.merge(class: cn("border-b last:border-b-0 group", @extra_class))
+      attrs[:open] = true if @open
+      attrs
+    end
+
+    def details_content
+      safe_join([
+        content_tag(:summary, summary_content, class: SUMMARY_CLASSES),
+        content_tag(:div, content, class: "pb-4 pt-0 text-sm")
+      ])
+    end
+
+    def summary_content
+      safe_join([
+        @title,
+        content_tag(:svg, content_tag(:path, nil, d: "m6 9 6 6 6-6"),
+          xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24",
+          fill: "none", stroke: "currentColor", stroke_width: "2",
+          stroke_linecap: "round", stroke_linejoin: "round",
+          class: "pointer-events-none size-4 shrink-0 translate-y-0.5 text-muted-foreground transition-transform duration-200 group-open:rotate-180")
+      ])
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/alert/alert_component.rb.tt

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module UI
+  class AlertComponent < ApplicationComponent
+    OUTER_CLASSES = "relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border " \
+                    "px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] " \
+                    "has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current"
+
+    VARIANTS = {
+      default: "bg-card text-card-foreground",
+      destructive: "bg-card text-destructive [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90"
+    }.freeze
+
+    renders_one :alert_title, "UI::AlertComponent::TitleComponent"
+    renders_one :alert_description, "UI::AlertComponent::DescriptionComponent"
+
+    # title: and description: are kwargs shorthands for plain-text content.
+    # Use slots (with_alert_title / with_alert_description) for rich HTML content.
+    # Slots take precedence over kwargs when both are provided.
+    def initialize(variant: :default, title: nil, description: nil)
+      @variant = variant.to_sym
+      @title = title
+      @description = description
+    end
+
+    def call
+      content_tag(:div, safe_join([resolved_title, resolved_description].compact),
+        role: "alert",
+        class: cn(OUTER_CLASSES, VARIANTS.fetch(@variant, VARIANTS[:default])))
+    end
+
+    class TitleComponent < ApplicationComponent
+      CLASSES = "col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight"
+
+      def call
+        content_tag(:h5, content, class: CLASSES)
+      end
+    end
+
+    class DescriptionComponent < ApplicationComponent
+      CLASSES = "col-start-2 grid justify-items-start gap-1 text-sm text-muted-foreground [&_p]:leading-relaxed"
+
+      def call
+        content_tag(:div, content, class: CLASSES, data: { slot: "alert-description" })
+      end
+    end
+
+    private
+
+    def resolved_title
+      alert_title || (@title && content_tag(:h5, @title, class: TitleComponent::CLASSES))
+    end
+
+    def resolved_description
+      return alert_description if alert_description
+
+      @description && content_tag(:div, @description,
+        class: DescriptionComponent::CLASSES,
+        data: { slot: "alert-description" })
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/alert_dialog/alert_dialog_component.rb.tt

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module UI
+  class AlertDialogComponent < ApplicationComponent
+    renders_one :trigger
+    renders_one :footer
+
+    OVERLAY = "fixed inset-0 z-50 bg-black/80"
+    PANEL   = "fixed left-[50%] top-[50%] z-50 w-full max-w-lg " \
+              "translate-x-[-50%] translate-y-[-50%] " \
+              "rounded-lg border bg-background p-6 shadow-lg"
+
+    def initialize(title: nil, description: nil, **html_attrs)
+      @title       = title
+      @description = description
+      @extra_class = html_attrs.delete(:class)
+      @html_attrs  = html_attrs
+    end
+
+    def call
+      content_tag(:div, data: { controller: "dialog" }, **@html_attrs) do
+        concat content_tag(:span, trigger, data: { action: "click->dialog#open" }, class: "contents") if trigger
+        concat panel
+      end
+    end
+
+    private
+
+    def panel
+      content_tag(:div, data: { dialog_target: "panel" }, hidden: true) do
+        concat content_tag(:div, nil,
+          class: OVERLAY,
+          "aria-hidden": "true")
+        concat content_tag(:div,
+          class: cn(PANEL, @extra_class),
+          role: "alertdialog",
+          "aria-modal": "true",
+          "aria-label": @title) {
+          concat header_area
+          concat content_tag(:div, content, class: "py-1 text-sm text-muted-foreground") unless content.blank?
+          concat content_tag(:div, footer, class: "mt-6 flex justify-end gap-2") if footer
+        }
+      end
+    end
+
+    def header_area
+      return "" if @title.nil? && @description.nil?
+
+      content_tag(:div, class: "mb-4") do
+        concat content_tag(:h2, @title, class: "text-lg font-semibold leading-none tracking-tight") if @title
+        concat content_tag(:p, @description, class: "mt-2 text-sm text-muted-foreground") if @description
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/aspect_ratio/aspect_ratio_component.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module UI
+  class AspectRatioComponent < ApplicationComponent
+    def initialize(ratio: 1, **html_attrs)
+      @ratio = ratio
+      @extra_class = html_attrs.delete(:class)
+      @html_attrs = html_attrs
+    end
+
+    def call
+      content_tag(:div, content,
+        style: "aspect-ratio: #{@ratio}",
+        class: cn("overflow-hidden", @extra_class),
+        **@html_attrs)
+    end
+  end
+end