view_primitives 0.1.0

data/lib/generators/view_primitives/add/templates/tooltip/tooltip_component.rb.tt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module UI
+  class TooltipComponent < ApplicationComponent
+    BUBBLE_BASE = "absolute z-50 w-fit rounded-md px-3 py-1.5 text-xs text-balance " \
+                  "bg-foreground text-background " \
+                  "opacity-0 group-hover:opacity-100 pointer-events-none whitespace-nowrap " \
+                  "transition-opacity duration-200"
+
+    POSITIONS = {
+      top:    "bottom-full left-1/2 -translate-x-1/2 mb-2",
+      bottom: "top-full left-1/2 -translate-x-1/2 mt-2",
+      left:   "right-full top-1/2 -translate-y-1/2 mr-2",
+      right:  "left-full top-1/2 -translate-y-1/2 ml-2"
+    }.freeze
+
+    def initialize(text:, side: :top, **html_attrs)
+      @text        = text
+      @side        = side.to_sym
+      @extra_class = html_attrs.delete(:class)
+      @html_attrs  = html_attrs
+    end
+
+    def call
+      content_tag(:span,
+        class: cn("relative inline-flex group", @extra_class),
+        **@html_attrs) do
+        concat content
+        concat tooltip_bubble
+      end
+    end
+
+    private
+
+    def tooltip_bubble
+      content_tag(:span,
+        @text,
+        class: cn(BUBBLE_BASE, POSITIONS.fetch(@side, POSITIONS[:top])),
+        role: "tooltip")
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/video/video_component.rb.tt

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module UI
+  class VideoComponent < ApplicationComponent
+    BASE = "max-w-full"
+
+    # Add <source> elements via v.with_source(src:, type:)
+    renders_many :sources, "UI::VideoComponent::SourceComponent"
+    # Add <track> elements via v.with_track(src:, kind:, label:, srclang:)
+    renders_many :tracks, "UI::VideoComponent::TrackComponent"
+
+    # poster:      URL of the preview image shown before playback
+    # controls:    show native browser controls (default: true)
+    # autoplay:    start playing automatically — requires muted: true
+    # muted:       mute the audio track
+    # loop:        loop playback
+    # preload:     :auto | :metadata (default) | :none
+    # playsinline: play inline on iOS instead of fullscreen
+    # width / height: explicit dimensions (prefer CSS or Aspect Ratio)
+    def initialize(poster: nil, controls: true, autoplay: false, muted: false,
+                   loop: false, preload: :metadata, playsinline: true,
+                   width: nil, height: nil, **html_attrs)
+      @poster      = poster
+      @controls    = controls
+      @autoplay    = autoplay
+      @muted       = muted
+      @loop        = loop
+      @preload     = preload
+      @playsinline = playsinline
+      @width       = width
+      @height      = height
+      @extra_class = html_attrs.delete(:class)
+      @html_attrs  = html_attrs
+    end
+
+    def call
+      attrs = { class: cn(BASE, @extra_class), preload: @preload }
+      attrs[:poster]      = @poster   if @poster
+      attrs[:controls]    = true      if @controls
+      attrs[:autoplay]    = true      if @autoplay
+      attrs[:muted]       = true      if @muted || @autoplay
+      attrs[:loop]        = true      if @loop
+      attrs[:playsinline] = true      if @playsinline
+      attrs[:width]       = @width    if @width
+      attrs[:height]      = @height   if @height
+
+      content_tag(:video, **attrs, **@html_attrs) do
+        sources.each { |s| concat s }
+        tracks.each  { |t| concat t }
+        concat content if content?
+      end
+    end
+
+    # Represents a <source> element inside <video>.
+    # v.with_source(src: "video.mp4", type: "video/mp4")
+    class SourceComponent < ApplicationComponent
+      def initialize(src:, type:, **html_attrs)
+        @src  = src
+        @type = type
+        @html_attrs = html_attrs
+      end
+
+      def call
+        tag.source(src: @src, type: @type, **@html_attrs)
+      end
+    end
+
+    # Represents a <track> element (captions, subtitles, chapters).
+    # v.with_track(src: "captions.vtt", kind: :subtitles, label: "English", srclang: "en")
+    # kind: :subtitles | :captions | :descriptions | :chapters | :metadata
+    class TrackComponent < ApplicationComponent
+      KINDS = %i[subtitles captions descriptions chapters metadata].freeze
+
+      def initialize(src:, kind: :subtitles, label: nil, srclang: nil, default: false, **html_attrs)
+        @src     = src
+        @kind    = KINDS.include?(kind.to_sym) ? kind.to_sym : :subtitles
+        @label   = label
+        @srclang = srclang
+        @default = default
+        @html_attrs = html_attrs
+      end
+
+      def call
+        attrs = { src: @src, kind: @kind }
+        attrs[:label]   = @label   if @label
+        attrs[:srclang] = @srclang if @srclang
+        attrs[:default] = true     if @default
+        tag.track(**attrs, **@html_attrs)
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/wysiwyg/wysiwyg_component.rb.tt

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module UI
+  class WysiwygComponent < ApplicationComponent
+    # Rich-text editor wrapper — picks between Trix and Quill via adapter:.
+    #
+    # Usage:
+    #   ui :wysiwyg, name: "body"                            # Trix (default)
+    #   ui :wysiwyg, name: "body", adapter: :quill
+    #   ui :wysiwyg, name: "body", adapter: :quill,
+    #     placeholder: "Write something...", height: 400
+    #
+    # Trix setup (ActionText):
+    #   bundle add actiontext
+    #   rails action_text:install
+    #
+    # Quill setup:
+    #   # config/importmap.rb
+    #   pin "quill", to: "https://esm.sh/quill@2"
+    #   # In your CSS entry point:
+    #   @import url("https://esm.sh/quill@2/dist/quill.snow.css");
+    #
+    # Options:
+    #   name:        form field name (required)
+    #   adapter:     :trix (default) | :quill
+    #   value:       initial HTML content
+    #   placeholder: placeholder text
+    #   toolbar:     show editor toolbar (default: true)
+    #   height:      editor content area height in px (default: 200; Quill only)
+
+    ADAPTERS = %w[trix quill].freeze
+
+    WRAPPER_CLS = "rounded-md border border-input bg-background shadow-xs"
+
+    def initialize(name:, adapter: :trix, value: nil, placeholder: nil,
+                   toolbar: true, height: 200, **html_attrs)
+      @name        = name
+      @adapter     = ADAPTERS.include?(adapter.to_s) ? adapter.to_s : "trix"
+      @value       = value
+      @placeholder = placeholder
+      @toolbar     = toolbar
+      @height      = height
+      @extra_class = html_attrs.delete(:class)
+      @html_attrs  = html_attrs
+      @input_id    = "wysiwyg-#{SecureRandom.hex(4)}"
+    end
+
+    def call
+      content_tag(:div, class: cn(WRAPPER_CLS, @extra_class)) do
+        @adapter == "quill" ? quill_markup : trix_markup
+      end
+    end
+
+    private
+
+    def trix_markup
+      safe_join([
+        tag.input(type: "hidden", id: @input_id, name: @name, value: @value),
+        tag.send(:"trix-editor",
+          input: @input_id,
+          placeholder: @placeholder,
+          class: "trix-content min-h-[200px] px-3 py-2 text-sm focus:outline-none")
+      ])
+    end
+
+    def quill_markup
+      content_tag(:div,
+        data: {
+          controller: "wysiwyg",
+          wysiwyg_adapter_value:      "quill",
+          wysiwyg_placeholder_value:  @placeholder.to_s,
+          wysiwyg_height_value:       @height,
+          wysiwyg_toolbar_value:      @toolbar
+        }) do
+        safe_join([
+          tag.div(
+            data: { wysiwyg_target: "editor" },
+            style: "height: #{@height}px"),
+          tag.input(
+            type: "hidden",
+            name: @name,
+            value: @value,
+            data: { wysiwyg_target: "input" })
+        ])
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/add/templates/wysiwyg/wysiwyg_controller.js

@@ -0,0 +1,40 @@
+// Quill adapter — requires Quill v2 in your importmap:
+//   pin "quill", to: "https://esm.sh/quill@2"
+// Also add Quill's stylesheet to your CSS entry point:
+//   @import url("https://esm.sh/quill@2/dist/quill.snow.css");
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["editor", "input"]
+  static values  = {
+    adapter:     { type: String,  default: "trix" },
+    placeholder: { type: String,  default: "" },
+    height:      { type: Number,  default: 200 },
+    toolbar:     { type: Boolean, default: true }
+  }
+
+  #quill = null
+
+  connect() {
+    if (this.adapterValue === "quill") this.#initQuill()
+  }
+
+  disconnect() {
+    this.#quill = null
+  }
+
+  async #initQuill() {
+    const { default: Quill } = await import("quill")
+    this.#quill = new Quill(this.editorTarget, {
+      theme: "snow",
+      placeholder: this.placeholderValue,
+      modules: { toolbar: this.toolbarValue }
+    })
+    if (this.inputTarget.value) {
+      this.#quill.root.innerHTML = this.inputTarget.value
+    }
+    this.#quill.on("text-change", () => {
+      this.inputTarget.value = this.#quill.root.innerHTML
+    })
+  }
+}

data/lib/generators/view_primitives/components.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ViewPrimitives
+  module Generators
+    module Components
+      TEMPLATE_ROOT = File.expand_path("add/templates", __dir__)
+
+      # Stimulus controllers not colocated with the component template directory.
+      EXTRA_STIMULUS = {
+        "alert_dialog" => {source: "dialog/dialog_controller.js", name: "dialog"}
+      }.freeze
+
+      # Post-install instructions for components that require external dependencies.
+      SETUP_NOTES = {
+        "chart" => <<~TEXT,
+          Chart requires Chart.js. Add it to your importmap:
+
+            # config/importmap.rb
+            pin "chart.js", to: "https://esm.sh/chart.js@4"
+
+          Then use the component:
+
+            ui :chart, type: :bar,
+              labels: ["Jan", "Feb", "Mar"],
+              datasets: [{ label: "Revenue", data: [100, 200, 150] }]
+        TEXT
+        "wysiwyg" => <<~TEXT
+          WYSIWYG defaults to Trix (adapter: :trix). To use Trix, install ActionText:
+
+            bundle add actiontext
+            rails action_text:install
+
+          To use Quill (adapter: :quill), add it to your importmap:
+
+            # config/importmap.rb
+            pin "quill", to: "https://esm.sh/quill@2"
+
+          Also add Quill's stylesheet to your CSS entry point:
+
+            @import url("https://esm.sh/quill@2/dist/quill.snow.css");
+
+          Usage:
+
+            ui :wysiwyg, name: "body"
+            ui :wysiwyg, name: "body", adapter: :quill, placeholder: "Write something..."
+        TEXT
+      }.freeze
+
+      def self.supported
+        @supported ||= Dir.children(TEMPLATE_ROOT).sort.freeze
+      end
+
+      def self.primary_path(component)
+        "app/components/ui/#{component}_component.rb"
+      end
+
+      def self.installed?(component, root)
+        File.exist?(File.join(root, primary_path(component)))
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/detector.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ViewPrimitives
+  module Generators
+    module Detector
+      TAILWIND_ENTRIES = [
+        {path: "app/assets/tailwind/application.css", stylesheets: "app/assets/stylesheets"},
+        {path: "app/assets/stylesheets/application.tailwind.css", stylesheets: "app/assets/stylesheets"},
+        {path: "app/assets/builds/tailwind.css", stylesheets: "app/assets/stylesheets"},
+        {path: "app/frontend/entrypoints/application.css", stylesheets: "app/frontend/stylesheets"},
+        {path: "app/javascript/entrypoints/application.css", stylesheets: "app/javascript/stylesheets"},
+        {path: "app/javascript/application.css", stylesheets: "app/javascript/stylesheets"}
+      ].freeze
+
+      JS_CONTROLLER_DIRS = %w[app/javascript/controllers app/frontend/controllers].freeze
+
+      private
+
+      def tailwind_entry
+        @tailwind_entry ||= TAILWIND_ENTRIES.find do |entry|
+          File.exist?(File.join(destination_root, entry[:path]))
+        end
+      end
+
+      def tailwind_entry_path = tailwind_entry&.fetch(:path)
+      def css_dest_dir = tailwind_entry&.fetch(:stylesheets) || "app/assets/stylesheets"
+      def css_dest_path = "#{css_dest_dir}/view_primitives.css"
+
+      def css_import_path
+        return unless tailwind_entry_path
+
+        Pathname.new("#{css_dest_dir}/view_primitives")
+          .relative_path_from(Pathname.new(File.dirname(tailwind_entry_path))).to_s
+      end
+
+      def js_controllers_dir
+        @js_controllers_dir ||= JS_CONTROLLER_DIRS.find do |dir|
+          File.exist?(File.join(destination_root, dir))
+        end
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/install/install_generator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../detector"
+
+module ViewPrimitives
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Detector
+
+      source_root File.expand_path("templates", __dir__)
+
+      def verify_ui_inflection
+        return if "ui/button".camelize == "UI::ButtonComponent"
+
+        say "\n  Warning: ActiveSupport inflection for `UI` is not configured.", :yellow
+        say "  ViewPrimitives expects `ui/button` to resolve to `UI::ButtonComponent`.", :yellow
+        say "  The gem registers this automatically — restart the Rails server if you just installed.\n", :yellow
+      end
+
+      def create_application_component
+        target = "app/components/application_component.rb"
+
+        if File.exist?(File.join(destination_root, target))
+          say "  ApplicationComponent already exists. Add `include ViewPrimitives::ClassHelper` manually.", :yellow
+        else
+          template "application_component.rb.tt", target
+        end
+      end
+
+      def create_css_variables
+        copy_file "view_primitives.css", css_dest_path
+      end
+
+      def inject_css_import
+        entry = tailwind_entry_path
+
+        unless entry
+          say "\n  Could not detect a Tailwind CSS entry point.", :yellow
+          say "  Add this line to your main CSS file:\n"
+          say "    @import \"./view_primitives\";\n"
+          say "  Common locations: app/assets/tailwind/application.css, " \
+              "app/assets/stylesheets/application.tailwind.css, app/javascript/application.css\n", :cyan
+          return
+        end
+
+        entry_content = File.read(File.join(destination_root, entry))
+
+        if entry_content.include?("view_primitives")
+          say "  #{entry} already imports view_primitives — skipping.", :yellow
+          return
+        end
+
+        import_line = "@import \"#{css_import_path}\";\n"
+
+        if entry_content.include?('@import "tailwindcss"')
+          inject_into_file entry, import_line, after: "@import \"tailwindcss\"\n"
+        elsif entry_content.include?("@import 'tailwindcss'")
+          inject_into_file entry, import_line, after: "@import 'tailwindcss'\n"
+        else
+          append_to_file entry, "\n#{import_line}"
+        end
+      end
+    end
+  end
+end

data/lib/generators/view_primitives/install/templates/application_component.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationComponent < ViewComponent::Base
+  include ViewPrimitives::ClassHelper
+end

data/lib/generators/view_primitives/install/templates/view_primitives.css

@@ -0,0 +1,67 @@
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --radius: 0.625rem;
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+}

data/lib/generators/view_primitives/list/list_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../components"
+
+module ViewPrimitives
+  module Generators
+    class ListGenerator < Rails::Generators::Base
+      desc "List available ViewPrimitives components and whether they are installed"
+
+      def list_components
+        say "\nViewPrimitives components:\n\n", :bold
+        say "COMPONENT          STATUS"
+        say "-" * 32
+
+        Components.supported.each do |component|
+          status = Components.installed?(component, destination_root) ? "installed" : "—"
+          color = (status == "installed") ? :green : :cyan
+          say format("%-18s %s", component, status), color
+        end
+
+        say "\nInstall: rails g view_primitives:add <name>\n", :cyan
+      end
+    end
+  end
+end

data/lib/view_primitives/class_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ViewPrimitives
+  module ClassHelper
+    private
+
+    def cn(*classes)
+      classes.flatten.compact.reject(&:empty?).join(" ")
+    end
+  end
+end

data/lib/view_primitives/component_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module ViewPrimitives
+  module ComponentHelper
+    #   <%= ui :button, variant: :outline do %>Click<% end %>
+    def ui(name, *, **, &)
+      klass = "UI::#{name.to_s.camelize}Component".safe_constantize
+
+      unless klass
+        raise ViewPrimitives::ComponentNotFoundError,
+          "Component `UI::#{name.to_s.camelize}Component` not found. " \
+          "Run `rails g view_primitives:add #{name}` to generate it."
+      end
+
+      render(klass.new(*, **), &)
+    end
+  end
+end

data/lib/view_primitives/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ViewPrimitives
+  class Railtie < Rails::Railtie
+    initializer "view_primitives.inflections" do
+      ActiveSupport::Inflector.inflections(:en) { |inflect| inflect.acronym "UI" }
+    end
+
+    generators do
+      %w[install add list].each do |gen|
+        require "generators/view_primitives/#{gen}/#{gen}_generator"
+      end
+    end
+
+    initializer "view_primitives.component_helper" do
+      %i[action_view action_mailer].each do |hook|
+        ActiveSupport.on_load(hook) { include ViewPrimitives::ComponentHelper }
+      end
+    end
+  end
+end

data/lib/view_primitives/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ViewPrimitives
+  VERSION = "0.1.0"
+end

data/lib/view_primitives.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "view_primitives/version"
+require_relative "view_primitives/class_helper"
+require_relative "view_primitives/component_helper"
+
+module ViewPrimitives
+  class Error < StandardError; end
+  class ComponentNotFoundError < Error; end
+end
+
+require_relative "view_primitives/railtie" if defined?(Rails::Railtie)