admin_suite 0.1.0

data/app/helpers/admin_suite/icon_helper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module IconHelper
+    # Renders an icon for AdminSuite using the configured renderer.
+    #
+    # Default behavior uses lucide-rails (LucideRails::IconProvider) if available.
+    # Back-compat: if `name` looks like raw SVG markup, it is returned as HTML safe.
+    #
+    # @param name [String, Symbol] icon name (e.g. "settings") OR raw svg string
+    # @param opts [Hash] passed to the underlying renderer (e.g. class:, stroke_width:)
+    # @return [ActiveSupport::SafeBuffer, String]
+    def admin_suite_icon(name, **opts)
+      return "".html_safe if name.blank?
+
+      raw = name.to_s
+      if raw.lstrip.start_with?("<svg")
+        return raw.html_safe
+      end
+
+      renderer = AdminSuite.config.icon_renderer
+      return renderer.call(raw, self, **opts) if renderer.respond_to?(:call)
+
+      # lucide-rails provides stripped SVG paths via IconProvider; we wrap them.
+      if defined?(::LucideRails::IconProvider)
+        default_class = "w-4 h-4"
+        css_class = [ default_class, opts[:class] ].compact.join(" ")
+        stroke_width = opts.fetch(:stroke_width, 2)
+        title = opts[:title]
+
+        begin
+          inner = ::LucideRails::IconProvider.icon(raw)
+        rescue ArgumentError
+          inner = nil
+        end
+
+        if inner.present?
+          return content_tag(
+            :svg,
+            (title.present? ? content_tag(:title, title) + inner.html_safe : inner.html_safe),
+            class: css_class,
+            xmlns: "http://www.w3.org/2000/svg",
+            width: "24",
+            height: "24",
+            viewBox: "0 0 24 24",
+            fill: "none",
+            stroke: "currentColor",
+            "stroke-width" => stroke_width,
+            "stroke-linecap" => "round",
+            "stroke-linejoin" => "round",
+            "aria-hidden" => "true",
+            focusable: "false"
+          )
+        end
+      end
+
+      # Safety fallback if lucide-rails isn't available in the host app for any reason.
+      content_tag(:span, "", class: opts[:class] || "inline-block w-4 h-4", title: raw)
+    end
+  end
+end

data/app/helpers/admin_suite/panels_helper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module PanelsHelper
+    # Renders a portal dashboard rows grid.
+    #
+    # @param rows [Array<AdminSuite::UI::RowDefinition>]
+    def render_dashboard_rows(rows)
+      return "" if rows.blank?
+
+      content_tag(:div, class: "space-y-6") do
+        rows.each do |row|
+          concat(content_tag(:div, class: "grid grid-cols-1 lg:grid-cols-12 gap-6") do
+            Array(row.panels).each do |panel|
+              concat(render_panel(panel))
+            end
+          end)
+        end
+      end
+    end
+
+    # Renders a single panel by selecting a partial.
+    #
+    # Host apps can override by setting `AdminSuite.config.partials[:panel_<type>]`.
+    #
+    # @param panel [AdminSuite::UI::PanelDefinition]
+    def render_panel(panel)
+      type = panel.type.to_sym
+      override = AdminSuite.config.partials[:"panel_#{type}"] rescue nil
+      partial = override.presence || "admin_suite/panels/#{type}"
+      span = (panel.options[:span] || 12).to_i
+      span = 12 if span < 1
+      span = 12 if span > 12
+
+      # Avoid dynamic Tailwind class generation (e.g. `lg:col-span-#{span}`),
+      # which would otherwise require a safelist.
+      content_tag(:div, style: "grid-column: span #{span} / span #{span};") do
+        render partial:, locals: { panel: panel }
+      end
+    end
+
+    # Evaluates a panel option, calling Procs if needed.
+    #
+    # @param value [Object, Proc]
+    # @return [Object]
+    def panel_eval(value)
+      return value.call if value.is_a?(Proc) && value.arity == 0
+      return value.call(self) if value.is_a?(Proc) && value.arity == 1
+      value
+    end
+  end
+end

data/app/helpers/admin_suite/resources_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module ResourcesHelper
+    # Intentionally empty.
+    #
+    # `AdminSuite::ApplicationController` installs `AdminSuite::BaseHelper` for all
+    # engine views. That helper provides rich rendering for:
+    # - index column types (e.g. `:toggle`, `:label`)
+    # - show formatters (markdown/json/code/attachments)
+    #
+    # Defining `render_column_value` / `format_show_value` here would override
+    # those implementations and silently break functionality.
+  end
+end

data/app/helpers/admin_suite/theme_helper.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module AdminSuite
+  module ThemeHelper
+    def admin_suite_theme
+      (AdminSuite.config.theme || {}).symbolize_keys
+    rescue StandardError
+      {}
+    end
+
+    def theme_primary
+      admin_suite_theme[:primary]
+    end
+
+    def theme_secondary
+      admin_suite_theme[:secondary]
+    end
+
+    # Returns a <style> tag that scopes theme variables to AdminSuite.
+    #
+    # This is the core of engine-build mode theming: UI classes stay static
+    # (no `bg-#{...}`), and color changes are driven by CSS variables.
+    def admin_suite_theme_style_tag
+      theme = admin_suite_theme
+
+      primary = theme[:primary]
+      secondary = theme[:secondary]
+
+      primary_name =
+        if AdminSuite::ThemePalette.hex?(primary)
+          nil
+        else
+          AdminSuite::ThemePalette.normalize_color(primary, default_name: :indigo)
+        end
+
+      secondary_name =
+        if AdminSuite::ThemePalette.hex?(secondary)
+          nil
+        else
+          AdminSuite::ThemePalette.normalize_color(secondary, default_name: :purple)
+        end
+
+      # Primary variables
+      primary_600 = AdminSuite::ThemePalette.hex?(primary) ? primary : AdminSuite::ThemePalette.resolve(primary_name, 600, fallback: "#4f46e5")
+      primary_700 = AdminSuite::ThemePalette.hex?(primary) ? primary : AdminSuite::ThemePalette.resolve(primary_name, 700, fallback: "#4338ca")
+
+      # Sidebar gradient variables (dark shades)
+      sidebar_from = AdminSuite::ThemePalette.resolve(primary_name || "indigo", 900, fallback: "#312e81")
+      sidebar_via = AdminSuite::ThemePalette.resolve(primary_name || "indigo", 800, fallback: "#3730a3")
+      sidebar_to =
+        if AdminSuite::ThemePalette.hex?(secondary)
+          secondary
+        else
+          AdminSuite::ThemePalette.resolve(secondary_name || "purple", 900, fallback: "#581c87")
+        end
+
+      css = <<~CSS
+        body.admin-suite {
+          --admin-suite-primary: #{primary_600};
+          --admin-suite-primary-hover: #{primary_700};
+          --admin-suite-sidebar-from: #{sidebar_from};
+          --admin-suite-sidebar-via: #{sidebar_via};
+          --admin-suite-sidebar-to: #{sidebar_to};
+        }
+      CSS
+
+      content_tag(:style, css.html_safe)
+    end
+
+    def theme_link_class
+      "admin-suite-link"
+    end
+
+    def theme_link_hover_text_class
+      "admin-suite-link-hover"
+    end
+
+    def theme_btn_primary_class
+      "admin-suite-btn-primary"
+    end
+
+    def theme_btn_primary_small_class
+      "admin-suite-btn-primary admin-suite-btn-primary--sm"
+    end
+
+    def theme_badge_primary_class
+      "admin-suite-badge-primary"
+    end
+
+    def theme_focus_ring_class
+      "admin-suite-focus-ring"
+    end
+
+    def theme_sidebar_gradient_class
+      # Deprecated: gradient is now CSS-variable driven (see `admin_suite_theme_style_tag`).
+      ""
+    end
+  end
+end

data/app/javascript/controllers/admin_suite/click_actions_controller.js

@@ -0,0 +1,73 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Utility controller for common click/change actions (Admin Suite).
+export default class extends Controller {
+  static values = {
+    modalId: String,
+    url: String,
+    inputId: String,
+    fallbackUrl: String,
+  }
+
+  openModal(event) {
+    event.preventDefault()
+    const modal = document.getElementById(this.modalIdValue)
+    if (modal) {
+      modal.dispatchEvent(new CustomEvent("modal:show"))
+    } else if (this.hasFallbackUrlValue) {
+      window.location.href = this.fallbackUrlValue
+    }
+  }
+
+  closeModal(event) {
+    event.preventDefault()
+    const modal = document.getElementById(this.modalIdValue)
+    if (modal) {
+      modal.dispatchEvent(new CustomEvent("modal:hide"))
+    }
+  }
+
+  hideModal(event) {
+    event.preventDefault()
+    const modal = document.getElementById(this.modalIdValue)
+    if (modal) {
+      modal.classList.add("hidden")
+    }
+  }
+
+  navigate(event) {
+    const clickedInteractive = event.target.closest(
+      "a, button, input, select, textarea, [data-action]",
+    )
+    if (clickedInteractive && clickedInteractive !== this.element) {
+      return
+    }
+    if (this.hasUrlValue) {
+      window.location.href = this.urlValue
+    }
+  }
+
+  redirectToValue(event) {
+    const value = event.target.value
+    if (value) {
+      window.location.href = value
+    }
+  }
+
+  clearAndSubmit(event) {
+    event.preventDefault()
+    const input = document.getElementById(this.inputIdValue)
+    if (input) {
+      input.value = ""
+      const form = input.closest("form")
+      if (form) {
+        form.requestSubmit()
+      }
+    }
+  }
+
+  stopPropagation(event) {
+    event.stopPropagation()
+  }
+}
+

data/app/javascript/controllers/admin_suite/clipboard_controller.js

@@ -0,0 +1,57 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Clipboard controller (Admin Suite) for copying text to clipboard.
+export default class extends Controller {
+  static values = {
+    text: String,
+  }
+
+  async copy(event) {
+    event.preventDefault()
+
+    try {
+      await navigator.clipboard.writeText(this.textValue)
+      this.showFeedback("Copied!")
+    } catch (_err) {
+      this.fallbackCopy(this.textValue)
+    }
+  }
+
+  fallbackCopy(text) {
+    const textarea = document.createElement("textarea")
+    textarea.value = text
+    textarea.style.position = "fixed"
+    textarea.style.opacity = "0"
+    document.body.appendChild(textarea)
+    textarea.select()
+
+    try {
+      document.execCommand("copy")
+      this.showFeedback("Copied!")
+    } catch (_err) {
+      this.showFeedback("Failed to copy")
+    }
+
+    document.body.removeChild(textarea)
+  }
+
+  showFeedback(message) {
+    const tooltip = document.createElement("div")
+    tooltip.textContent = message
+    tooltip.className =
+      "fixed z-50 px-2 py-1 text-xs font-medium text-white bg-gray-900 rounded shadow-lg pointer-events-none transition-opacity duration-200"
+
+    const rect = this.element.getBoundingClientRect()
+    tooltip.style.top = `${rect.top - 30}px`
+    tooltip.style.left = `${rect.left + rect.width / 2}px`
+    tooltip.style.transform = "translateX(-50%)"
+
+    document.body.appendChild(tooltip)
+
+    setTimeout(() => {
+      tooltip.style.opacity = "0"
+      setTimeout(() => tooltip.remove(), 200)
+    }, 1000)
+  }
+}
+

data/app/javascript/controllers/admin_suite/code_editor_controller.js

@@ -0,0 +1,45 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Code Editor Controller (Admin Suite)
+ *
+ * Lightweight fallback: keeps a monospace textarea but adds
+ * - tab indentation support
+ * - auto-resize (optional)
+ *
+ * If a host app wants a real editor (CodeMirror/Monaco), it can override by
+ * replacing this controller via importmap pinning.
+ */
+export default class extends Controller {
+  static targets = ["textarea"]
+
+  connect() {
+    if (!this.hasTextareaTarget) return
+
+    this.onKeydown = this.onKeydown.bind(this)
+    this.textareaTarget.addEventListener("keydown", this.onKeydown)
+  }
+
+  disconnect() {
+    if (!this.hasTextareaTarget) return
+    this.textareaTarget.removeEventListener("keydown", this.onKeydown)
+  }
+
+  onKeydown(event) {
+    if (event.key !== "Tab") return
+
+    event.preventDefault()
+    const el = this.textareaTarget
+    const start = el.selectionStart
+    const end = el.selectionEnd
+    const value = el.value
+
+    // Insert two spaces on tab.
+    el.value = value.substring(0, start) + "  " + value.substring(end)
+    el.selectionStart = el.selectionEnd = start + 2
+
+    // Keep Rails form dirty tracking happy.
+    el.dispatchEvent(new Event("input", { bubbles: true }))
+  }
+}
+

data/app/javascript/controllers/admin_suite/file_upload_controller.js

@@ -0,0 +1,238 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * File Upload Controller (Admin Suite)
+ */
+export default class extends Controller {
+  static targets = ["input", "filename", "dropzone", "imagePreview", "progress", "removeButton"]
+
+  static values = {
+    accept: { type: String, default: "" },
+    maxSize: { type: Number, default: 10485760 },
+    preview: { type: Boolean, default: false },
+    multiple: { type: Boolean, default: false },
+    existingUrl: String,
+  }
+
+  connect() {
+    this.setupDropZone()
+
+    if (this.existingUrlValue && this.hasImagePreviewTarget) {
+      this.showExistingPreview()
+    }
+  }
+
+  disconnect() {
+    if (this.dropZoneElement) {
+      this.dropZoneElement.removeEventListener("dragover", this.handleDragOver)
+      this.dropZoneElement.removeEventListener("dragleave", this.handleDragLeave)
+      this.dropZoneElement.removeEventListener("drop", this.handleDrop)
+    }
+  }
+
+  setupDropZone() {
+    this.dropZoneElement = this.hasDropzoneTarget ? this.dropzoneTarget : this.element
+
+    this.handleDragOver = this.onDragOver.bind(this)
+    this.handleDragLeave = this.onDragLeave.bind(this)
+    this.handleDrop = this.onDrop.bind(this)
+
+    this.dropZoneElement.addEventListener("dragover", this.handleDragOver)
+    this.dropZoneElement.addEventListener("dragleave", this.handleDragLeave)
+    this.dropZoneElement.addEventListener("drop", this.handleDrop)
+  }
+
+  preview(event) {
+    const files = event.target.files
+    if (files.length > 0) {
+      this.processFiles(files)
+    }
+  }
+
+  onDragOver(event) {
+    event.preventDefault()
+    event.stopPropagation()
+    this.dropZoneElement.classList.add("border-amber-500", "bg-amber-50", "dark:bg-amber-900/10")
+  }
+
+  onDragLeave(event) {
+    event.preventDefault()
+    event.stopPropagation()
+    this.dropZoneElement.classList.remove("border-amber-500", "bg-amber-50", "dark:bg-amber-900/10")
+  }
+
+  onDrop(event) {
+    event.preventDefault()
+    event.stopPropagation()
+    this.dropZoneElement.classList.remove("border-amber-500", "bg-amber-50", "dark:bg-amber-900/10")
+
+    const files = event.dataTransfer.files
+    if (files.length > 0) {
+      this.processFiles(files)
+    }
+  }
+
+  processFiles(files) {
+    const file = files[0]
+
+    if (!this.validateType(file)) {
+      this.showError(`Invalid file type. Allowed: ${this.acceptValue || "all files"}`)
+      return
+    }
+
+    if (!this.validateSize(file)) {
+      this.showError(`File too large. Maximum size: ${this.formatFileSize(this.maxSizeValue)}`)
+      return
+    }
+
+    if (this.hasInputTarget && !this.inputTarget.files.length) {
+      const dataTransfer = new DataTransfer()
+      dataTransfer.items.add(file)
+      this.inputTarget.files = dataTransfer.files
+    }
+
+    this.showFileInfo(file)
+
+    if (this.previewValue && this.isImage(file)) {
+      this.showImagePreview(file)
+    }
+
+    if (this.hasRemoveButtonTarget) {
+      this.removeButtonTarget.classList.remove("hidden")
+    }
+
+    this.dispatch("select", { detail: { file } })
+  }
+
+  validateType(file) {
+    if (!this.acceptValue) return true
+
+    const acceptTypes = this.acceptValue.split(",").map((t) => t.trim())
+
+    return acceptTypes.some((type) => {
+      if (type === "*/*") return true
+      if (type.endsWith("/*")) {
+        const category = type.replace("/*", "")
+        return file.type.startsWith(category)
+      }
+      if (type.startsWith(".")) {
+        return file.name.toLowerCase().endsWith(type.toLowerCase())
+      }
+      return file.type === type
+    })
+  }
+
+  validateSize(file) {
+    return file.size <= this.maxSizeValue
+  }
+
+  isImage(file) {
+    return file.type.startsWith("image/")
+  }
+
+  showFileInfo(file) {
+    if (!this.hasFilenameTarget) return
+
+    const fileName = file.name
+    const fileSize = this.formatFileSize(file.size)
+
+    this.filenameTarget.innerHTML = `
+      <div class="flex items-center gap-2">
+        <svg class="w-5 h-5 text-green-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path>
+        </svg>
+        <span class="font-medium text-slate-900 dark:text-white">${fileName}</span>
+        <span class="text-slate-500 dark:text-slate-400">(${fileSize})</span>
+      </div>
+    `
+  }
+
+  showImagePreview(file) {
+    if (!this.hasImagePreviewTarget) return
+
+    const reader = new FileReader()
+    reader.onload = (e) => {
+      this.imagePreviewTarget.src = e.target.result
+      this.imagePreviewTarget.classList.remove("hidden")
+    }
+    reader.readAsDataURL(file)
+  }
+
+  showExistingPreview() {
+    if (this.hasImagePreviewTarget && this.existingUrlValue) {
+      this.imagePreviewTarget.src = this.existingUrlValue
+      this.imagePreviewTarget.classList.remove("hidden")
+    }
+
+    if (this.hasRemoveButtonTarget) {
+      this.removeButtonTarget.classList.remove("hidden")
+    }
+  }
+
+  showError(message) {
+    if (!this.hasFilenameTarget) return
+
+    this.filenameTarget.innerHTML = `
+      <div class="flex items-center gap-2 text-red-600 dark:text-red-400">
+        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"></path>
+        </svg>
+        <span>${message}</span>
+      </div>
+    `
+
+    if (this.hasInputTarget) {
+      this.inputTarget.value = ""
+    }
+  }
+
+  showProgress(percent) {
+    if (!this.hasProgressTarget) return
+
+    this.progressTarget.classList.remove("hidden")
+    this.progressTarget.innerHTML = `
+      <div class="w-full bg-slate-200 dark:bg-slate-700 rounded-full h-2">
+        <div class="bg-amber-500 h-2 rounded-full transition-all duration-300" style="width: ${percent}%"></div>
+      </div>
+      <span class="text-xs text-slate-500 dark:text-slate-400">${percent}%</span>
+    `
+  }
+
+  hideProgress() {
+    if (this.hasProgressTarget) {
+      this.progressTarget.classList.add("hidden")
+    }
+  }
+
+  remove() {
+    if (this.hasInputTarget) {
+      this.inputTarget.value = ""
+    }
+
+    if (this.hasFilenameTarget) {
+      this.filenameTarget.innerHTML = `
+        <span class="text-slate-500 dark:text-slate-400">No file selected</span>
+      `
+    }
+
+    if (this.hasImagePreviewTarget) {
+      this.imagePreviewTarget.src = ""
+      this.imagePreviewTarget.classList.add("hidden")
+    }
+
+    if (this.hasRemoveButtonTarget) {
+      this.removeButtonTarget.classList.add("hidden")
+    }
+
+    this.dispatch("remove")
+  }
+
+  formatFileSize(bytes) {
+    if (bytes === 0) return "0 Bytes"
+    const k = 1024
+    const sizes = ["Bytes", "KB", "MB", "GB"]
+    const i = Math.floor(Math.log(bytes) / Math.log(k))
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i]
+  }
+}
+