panda-core 0.2.3 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 348ffbfa5cfbd2fc7fcb605670dd7ecb3914eddd6c076984d94d689d050e44fe
-  data.tar.gz: 50f977fc4f31605d4b985f9f37d3167b239a4b1627e2aaedb9638e10d7bd0762
+  metadata.gz: 1571548de89ff0ad16010f4500ed47a1c53dda70c730945fa439272a33567999
+  data.tar.gz: 02cc839e0831b886a37729b43a5d185d1bd7a13eb3ff59dd2e3afc0f7996e4cd
 SHA512:
-  metadata.gz: 077e81f9825f43dd1e65425fca186277ba082bab5b4e361a746dba2bbdf3224bdca7db055db47504ca6f4d345962129f58ba3b090557992472689a6e57f90f5a
-  data.tar.gz: 3be894b015597b1f06a12452398eef7c03824de92e553b1d8e960f161407ee9bf3d5cd6df43e57ea5eb7075cb4b16ac38bdeae6010f30fe11e962467e45b92d6
+  metadata.gz: acaebae64c9e8b970edda07e35f0b3820e988d3c738c3cf0c4d9c647be828d98773992d6a1ab70a4dc74cc01edaa04582a43c0fa285222a2e2d8169afaba7ac0
+  data.tar.gz: 927db64e6429b4687667e8e47b185abea96e1f50668b5e6abe2d36050a1606aac880610f94d2f08205fb4a1280e3c95f05f8c45a8afc1d03ca10a38fad0abdd5

data/README.md

@@ -59,6 +59,191 @@ The gems listed in the `panda-core.gemspec` will be added to your Gemfile (or, i
 
 Make sure to follow the setup instructions for each of these gems.
 
+## Configuration
+
+Panda Core is configured in `config/initializers/panda.rb`. The install generator creates this file with a complete default configuration:
+
+```ruby
+# config/initializers/panda.rb
+Panda::Core.configure do |config|
+  config.admin_path = "/admin"
+
+  config.login_page_title = "Panda Admin"
+  config.admin_title = "Panda Admin"
+
+  config.authentication_providers = {
+    google_oauth2: {
+      enabled: true,
+      name: "Google",
+      client_id: Rails.application.credentials.dig(:google, :client_id),
+      client_secret: Rails.application.credentials.dig(:google, :client_secret),
+      options: {
+        scope: "email,profile",
+        prompt: "select_account",
+        hd: "yourdomain.com" # Restrict to specific domain
+      }
+    }
+  }
+
+  # Core settings
+  config.session_token_cookie = :panda_session
+  config.user_class = "Panda::Core::User"
+  config.user_identity_class = "Panda::Core::UserIdentity"
+  config.storage_provider = :active_storage
+  config.cache_store = :memory_store
+
+  # Optional editor configuration
+  # config.editor_js_tools = []
+  # config.editor_js_tool_config = {}
+end
+```
+
+### Authentication Providers
+
+Panda Core supports multiple OAuth providers. Configure your credentials in Rails credentials:
+
+```yaml
+# config/credentials.yml.enc
+google:
+  client_id: "your-google-client-id"
+  client_secret: "your-google-client-secret"
+
+microsoft:
+  client_id: "your-microsoft-client-id"
+  client_secret: "your-microsoft-client-secret"
+```
+
+Then reference them in your initializer. You can enable multiple providers simultaneously.
+
+### Admin Path
+
+The `admin_path` setting controls where the admin interface is mounted (default: `/admin`). You can customize this to avoid route conflicts or match your preferences:
+
+```ruby
+config.admin_path = "/manage"  # Custom admin path
+```
+
+This is useful when:
+- You want to avoid conflicts with existing routes
+- You prefer a different URL structure
+- You're running multiple admin interfaces
+- You need different admin paths per environment
+
+### Asset Pipeline
+
+Panda Core provides the **single source of truth** for all Panda admin interface styling. This includes:
+
+- Base Tailwind CSS utilities and theme system
+- EditorJS content styles (used by Panda CMS)
+- Admin component styles
+- Form styles and typography
+
+**Asset Compilation**
+
+Panda Core uses Tailwind CSS v4 to compile all admin interface styling.
+
+**Quick Start** - Compile full CSS (Core + CMS):
+
+```bash
+cd /path/to/panda-core
+
+bundle exec tailwindcss -i app/assets/tailwind/application.css \
+  -o public/panda-core-assets/panda-core.css \
+  --content '../cms/app/views/**/*.erb' \
+  --content '../cms/app/components/**/*.rb' \
+  --content '../cms/app/javascript/**/*.js' \
+  --content 'app/views/**/*.erb' \
+  --content 'app/components/**/*.rb' \
+  --minify
+```
+
+**Result**: `panda-core.css` (~37KB) with all utility classes
+
+**Important**: Always compile with full content before committing!
+
+For complete documentation on:
+- Development workflows (Core-only vs full stack)
+- Release processes
+- Troubleshooting
+- Best practices
+
+See **[docs/ASSET_COMPILATION.md](docs/ASSET_COMPILATION.md)**
+
+**How Asset Serving Works:**
+
+Core's Rack middleware serves `/panda-core-assets/` from the gem's `public/` directory:
+
+```ruby
+# In Core's engine.rb
+config.app_middleware.use(Rack::Static,
+  urls: ["/panda-core-assets"],
+  root: Panda::Core::Engine.root.join("public")
+)
+```
+
+This means:
+- ✅ CMS and other gems automatically load CSS from Core
+- ✅ No copying needed - served directly from gem
+- ✅ Version changes are instant (just restart server)
+- ✅ Single source of truth for all admin styling
+
+**What Gets Compiled:**
+
+The compilation process:
+- Scans all Core and CMS views/components for Tailwind classes (via `tailwind.config.js`)
+- Includes EditorJS content styles for rich text editing
+- Applies theme variables for default and sky themes
+- Outputs a single minified CSS file (~37KB)
+
+**Asset Serving**
+
+Panda Core automatically serves compiled assets from `/panda-core-assets/` using Rack::Static middleware configured in the engine.
+
+**How Panda CMS Uses Core Styling**
+
+Panda CMS depends on Panda Core and loads its CSS automatically:
+
+```erb
+<!-- In CMS views -->
+<link rel="stylesheet" href="/panda-core-assets/panda-core.css">
+```
+
+CMS no longer compiles its own CSS - all styling comes from Core.
+
+**Content Scanning**
+
+The `tailwind.config.js` file configures content scanning to include:
+- Core views: `../../app/views/**/*.html.erb`
+- Core components: `../../app/components/**/*.rb`
+- CMS views: `../../../cms/app/views/**/*.html.erb`
+- CMS components: `../../../cms/app/components/**/*.rb`
+- CMS JavaScript: `../../../cms/app/javascript/**/*.js`
+
+This ensures all Tailwind classes used across the Panda ecosystem are included in the compiled CSS.
+
+**Customizing Styles**
+
+To customize the admin interface styles:
+
+1. Edit `app/assets/tailwind/application.css` in panda-core
+2. Add custom CSS in the appropriate `@layer` (base, components, or utilities)
+3. Recompile: `bundle exec tailwindcss -i app/assets/tailwind/application.css -o public/panda-core-assets/panda-core.css --minify`
+4. Copy the updated CSS to test locations if needed
+5. Restart your Rails server to see changes
+
+**Theme System**
+
+Panda Core provides two built-in themes accessible via `data-theme` attribute:
+
+- `default`: Purple/pink color scheme
+- `sky`: Blue color scheme
+
+Themes use CSS custom properties that can be referenced in your styles:
+- `--color-white`, `--color-black`
+- `--color-light`, `--color-mid`, `--color-dark`
+- `--color-highlight`, `--color-active`, `--color-inactive`
+- `--color-warning`, `--color-error`
+
 ## Development
 
 After checking out the repo:

data/app/assets/tailwind/application.css

@@ -0,0 +1,279 @@
+@import 'tailwindcss';
+
+@source "../../app/views/**/*.html.erb";
+@source "../../app/components/**/*.html.erb";
+@source "../../app/components/**/*.rb";
+@source "../../app/helpers/**/*.rb";
+@source "../../../cms/app/views/**/*.html.erb";
+@source "../../../cms/app/components/**/*.html.erb";
+@source "../../../cms/app/components/**/*.rb";
+
+@theme {
+  --color-white: var(--color-white);
+  --color-black: var(--color-black);
+  --color-light: var(--color-light);
+  --color-mid: var(--color-mid);
+  --color-dark: var(--color-dark);
+  --color-highlight: var(--color-highlight);
+  --color-active: var(--color-active);
+  --color-inactive: var(--color-inactive);
+  --color-warning: var(--color-warning);
+  --color-error: var(--color-error);
+}
+
+@layer base {
+  html[data-theme='default'] {
+    --color-white: rgb(249, 249, 249); /* #F9F9F9 */
+    --color-black: rgb(26, 22, 29); /* #1A161D */
+
+    --color-light: rgb(238, 206, 230); /* #EECEE6 */
+    --color-mid: rgb(141, 94, 183); /* #8D5EB7 */
+    --color-dark: rgb(33, 29, 73); /* #211D49 */
+
+    --color-highlight: rgb(208, 64, 20); /* #D04014 */
+
+    --color-active: rgb(0, 135, 85); /* #008755 */
+    --color-warning: rgb(250, 207, 142); /* #FACF8E */
+    --color-inactive: rgb(216, 247, 245); /* #d6e4f7 */
+    --color-error: rgb(245, 129, 129); /* #F58181 */
+  }
+
+  html[data-theme='sky'] {
+    --color-white: rgb(249, 249, 249); /* #F9F9F9 */
+    --color-black: rgb(26, 22, 29); /* #1A161D */
+    --color-light: rgb(204, 238, 242); /* #CCEEF2 */
+    --color-mid: rgb(42, 102, 159); /* #2A669F */
+    --color-dark: rgb(20, 32, 74); /* #14204A */
+    --color-highlight: rgb(208, 64, 20); /* #D04014 */
+
+    --color-active: rgb(69, 154, 89); /* #459A59 - darker green with better contrast */
+    --color-warning: rgb(244, 190, 102); /* #F4BE66 */
+    --color-inactive: rgb(216, 247, 245); /* #d6e4f7 */
+    --color-error: rgb(208, 64, 20); /* #D04014 */
+  }
+
+  a.block-link:after {
+    position: absolute;
+    content: '';
+    inset: 0;
+  }
+
+  /* Admin gradient backgrounds */
+  html[data-theme='default'] .bg-gradient-admin {
+    background: linear-gradient(to bottom right, rgb(33, 29, 73), rgb(141, 94, 183));
+  }
+
+  html[data-theme='sky'] .bg-gradient-admin {
+    background: linear-gradient(to bottom right, rgb(20, 32, 74), rgb(42, 102, 159));
+  }
+}
+
+/* Form input styles */
+@layer components {
+  /* Base form field styles - matches panda-cms admin pattern */
+  input[type='text'],
+  input[type='email'],
+  input[type='password'],
+  input[type='url'],
+  input[type='tel'],
+  input[type='number'],
+  input[type='date'],
+  input[type='datetime-local'],
+  input[type='month'],
+  input[type='week'],
+  input[type='time'],
+  input[type='search'],
+  textarea {
+    @apply block w-full rounded-md border-0 p-2 text-gray-900 bg-white;
+    @apply ring-1 ring-inset ring-mid placeholder:text-gray-300;
+    @apply focus:ring-1 focus:ring-inset focus:ring-dark;
+    @apply hover:cursor-pointer sm:leading-6;
+    @apply disabled:ring-gray-300 disabled:focus:ring-gray-300 disabled:bg-gray-50 disabled:cursor-not-allowed;
+  }
+
+  /* Select specific styling - matches panda-cms admin pattern */
+  select {
+    @apply block w-full rounded-md border-0 py-1.5 pl-3 pr-10 text-gray-900 bg-white;
+    @apply ring-1 ring-inset ring-mid;
+    @apply focus:ring-1 focus:ring-inset focus:ring-dark;
+    @apply hover:cursor-pointer sm:leading-6;
+    @apply disabled:ring-gray-300 disabled:focus:ring-gray-300 disabled:bg-gray-50 disabled:cursor-not-allowed;
+    @apply appearance-none bg-right bg-no-repeat;
+    background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3e%3cpath stroke='%236b7280' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' d='M6 8l4 4 4-4'/%3e%3c/svg%3e");
+    background-position: right 0.5rem center;
+    background-size: 1.5em 1.5em;
+  }
+
+  /* Checkbox and radio styling */
+  input[type='checkbox'],
+  input[type='radio'] {
+    @apply w-4 h-4 text-indigo-600 bg-white border-gray-300 rounded transition-colors duration-200;
+    @apply focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2;
+    @apply disabled:bg-gray-100 disabled:cursor-not-allowed;
+  }
+
+  input[type='radio'] {
+    @apply rounded-full;
+  }
+
+  /* Label styling */
+  label {
+    @apply block text-sm font-medium text-gray-700 mb-1;
+  }
+
+  /* Field wrapper styling */
+  .field {
+    @apply mb-4;
+  }
+
+  /* Error state styling */
+  input.error,
+  textarea.error,
+  select.error {
+    @apply ring-red-500 focus:ring-red-500;
+  }
+
+  .field-error {
+    @apply text-sm text-red-600 mt-1;
+  }
+
+  /* Button styling */
+  .btn {
+    @apply inline-flex items-center justify-center px-6 py-3 text-base font-semibold rounded-md transition-colors duration-200;
+    @apply focus:outline-none focus:ring-2 focus:ring-offset-2;
+    @apply disabled:opacity-50 disabled:cursor-not-allowed;
+  }
+
+  .btn-primary {
+    @apply bg-mid text-white hover:opacity-90 focus:ring-mid;
+  }
+
+  .btn-secondary {
+    @apply bg-gray-200 text-gray-900 hover:bg-gray-300 focus:ring-gray-500;
+  }
+
+  .btn-danger {
+    @apply bg-red-600 text-white hover:bg-red-700 focus:ring-red-500;
+  }
+}
+
+/* EditorJS content styles */
+@layer components {
+  .codex-editor__redactor .ce-block .ce-block__content {
+    @apply text-base font-normal font-sans text-dark leading-[1.6] space-y-[1.6rem];
+
+    h1.ce-header {
+      @apply text-3xl md:text-4xl font-semibold font-sans leading-[1.2];
+    }
+
+    h2.ce-header {
+      @apply text-2xl font-medium font-sans leading-[1.3] mb-4 mt-8;
+    }
+
+    h3.ce-header {
+      @apply text-xl font-normal font-sans leading-[1.3] mb-4 mt-6;
+    }
+
+    p,
+    li {
+      @apply leading-[1.6] tracking-wide max-w-[85ch];
+
+      a {
+        @apply text-[#1A9597] underline underline-offset-2 hover:text-[#158486] focus:outline-2 focus:outline-offset-2 focus:outline-[#1A9597];
+      }
+
+      strong,
+      b {
+        @apply font-semibold;
+      }
+    }
+
+    p {
+      @apply mb-4;
+    }
+
+    .cdx-quote {
+      @apply bg-[#eef0f3] border-l-inactive border-l-8 p-6 mb-4;
+
+      .cdx-quote__caption {
+        @apply block ml-6 mt-2 text-sm text-dark;
+      }
+
+      .cdx-quote__text {
+        quotes: '\201C' '\201D' '\2018' '\2019';
+        @apply pl-6;
+
+        &:before {
+          @apply -ml-8 mr-2 text-dark text-6xl leading-4 align-text-bottom font-serif;
+          content: open-quote;
+        }
+
+        p {
+          @apply inline italic text-lg;
+        }
+      }
+    }
+
+    .cdx-list {
+      @apply mb-4 pl-6;
+
+      &--ordered {
+        @apply list-decimal;
+      }
+
+      &--unordered {
+        @apply list-disc;
+      }
+
+      .cdx-list {
+        @apply mt-2 mb-0;
+      }
+
+      .cdx-list__item {
+        @apply mb-2 pl-2;
+      }
+    }
+
+    .cdx-nested-list {
+      @apply mb-4 pl-6;
+
+      &--ordered {
+        @apply list-decimal;
+      }
+
+      &--unordered {
+        @apply list-disc;
+      }
+
+      .cdx-nested-list {
+        @apply mt-2 mb-0;
+      }
+
+      .cdx-nested-list__item {
+        @apply mb-2 pl-2;
+      }
+    }
+
+    .cdx-table {
+      @apply w-full border-collapse border-2 border-dark my-6;
+
+      &__head {
+        @apply font-semibold border-dark border-r-2 p-3 bg-light;
+      }
+
+      &__row {
+        @apply border-dark border-b-2;
+      }
+
+      &__cell {
+        @apply border-dark border-r-2 p-3;
+      }
+    }
+
+    .cdx-embed {
+      iframe {
+        @apply w-full border-none;
+      }
+    }
+  }
+}

data/app/assets/tailwind/tailwind.config.js

@@ -0,0 +1,21 @@
+module.exports = {
+  content: {
+    relative: true,
+    files: [
+      // Panda Core views and components
+      "../../app/views/**/*.html.erb",
+      "../../app/components/**/*.html.erb",
+      "../../app/components/**/*.rb",
+      "../../app/helpers/**/*.rb",
+
+      // Panda CMS views and components (for compilation)
+      "../../../cms/app/views/**/*.html.erb",
+      "../../../cms/app/builders/**/*.rb",
+      "../../../cms/app/components/**/*.html.erb",
+      "../../../cms/app/components/**/*.rb",
+      "../../../cms/app/helpers/**/*.rb",
+      "../../../cms/app/javascript/**/*.js",
+      "../../../cms/vendor/javascript/**/*.js",
+    ],
+  },
+};

data/app/components/panda/core/UI/badge.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    module UI
+      # Badge component for status indicators, labels, and counts.
+      #
+      # Badges are small, inline elements that highlight an item's status
+      # or provide additional metadata at a glance.
+      #
+      # @example Basic badge
+      #   render Panda::Core::UI::Badge.new(text: "New")
+      #
+      # @example Status badges
+      #   render Panda::Core::UI::Badge.new(text: "Active", variant: :success)
+      #   render Panda::Core::UI::Badge.new(text: "Pending", variant: :warning)
+      #   render Panda::Core::UI::Badge.new(text: "Error", variant: :danger)
+      #
+      # @example With count
+      #   render Panda::Core::UI::Badge.new(text: "99+", variant: :primary, size: :small)
+      #
+      # @example Removable badge
+      #   render Panda::Core::UI::Badge.new(
+      #     text: "Tag",
+      #     removable: true,
+      #     data: { action: "click->tags#remove" }
+      #   )
+      #
+      class Badge < Panda::Core::Base
+        prop :text, String
+        prop :variant, Symbol, default: :default
+        prop :size, Symbol, default: :medium
+        prop :removable, _Boolean, default: false
+        prop :rounded, _Boolean, default: false
+
+        def view_template
+          span(**@attrs) do
+            plain text
+            if removable
+              whitespace
+              button(
+                type: "button",
+                class: "inline-flex items-center ml-1 hover:opacity-70",
+                aria: {label: "Remove"}
+              ) do
+                svg(
+                  class: "h-3 w-3",
+                  xmlns: "http://www.w3.org/2000/svg",
+                  viewBox: "0 0 20 20",
+                  fill: "currentColor"
+                ) do |s|
+                  s.path(
+                    d: "M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z"
+                  )
+                end
+              end
+            end
+          end
+        end
+
+        def default_attrs
+          {
+            class: badge_classes
+          }
+        end
+
+        private
+
+        def badge_classes
+          base = "inline-flex items-center font-medium"
+          base += " #{size_classes}"
+          base += " #{variant_classes}"
+          base += rounded ? " rounded-full" : " rounded"
+          base
+        end
+
+        def size_classes
+          case size
+          when :small, :sm
+            "px-2 py-0.5 text-xs"
+          when :large, :lg
+            "px-3 py-1 text-base"
+          else # :medium, :md
+            "px-2.5 py-0.5 text-sm"
+          end
+        end
+
+        def variant_classes
+          case variant
+          when :primary
+            "bg-blue-50 text-blue-700 ring-1 ring-inset ring-blue-700/10"
+          when :success
+            "bg-green-50 text-green-700 ring-1 ring-inset ring-green-600/20"
+          when :warning
+            "bg-yellow-50 text-yellow-800 ring-1 ring-inset ring-yellow-600/20"
+          when :danger
+            "bg-red-50 text-red-700 ring-1 ring-inset ring-red-600/10"
+          when :info
+            "bg-sky-50 text-sky-700 ring-1 ring-inset ring-sky-700/10"
+          else # :default
+            "bg-gray-50 text-gray-600 ring-1 ring-inset ring-gray-500/10"
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/panda/core/UI/button.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    module UI
+      # Modern Phlex-based button component with type-safe props.
+      #
+      # This component demonstrates the recommended pattern for building
+      # Phlex components in the Panda ecosystem using the shared base class.
+      #
+      # @example Basic usage
+      #   render Panda::Core::UI::Button.new(text: "Click me")
+      #
+      # @example With variant
+      #   render Panda::Core::UI::Button.new(
+      #     text: "Delete",
+      #     variant: :danger,
+      #     size: :large
+      #   )
+      #
+      # @example With custom attributes
+      #   render Panda::Core::UI::Button.new(
+      #     text: "Submit",
+      #     variant: :primary,
+      #     class: "mt-4",
+      #     data: { turbo_method: :post }
+      #   )
+      #
+      class Button < Panda::Core::Base
+        # Type-safe properties using Literal
+        prop :text, String
+        prop :variant, Symbol, default: :default
+        prop :size, Symbol, default: :medium
+        prop :disabled, _Boolean, default: false
+        prop :type, String, default: "button"
+
+        def view_template
+          button(**@attrs) { text }
+        end
+
+        def default_attrs
+          {
+            type: type,
+            disabled: disabled,
+            class: button_classes
+          }
+        end
+
+        private
+
+        def button_classes
+          base = "inline-flex items-center rounded-md font-medium shadow-sm transition-colors"
+          base += " #{size_classes}"
+          base += " #{variant_classes}"
+          base += " disabled:opacity-50 disabled:cursor-not-allowed" if disabled
+          base
+        end
+
+        def size_classes
+          case size
+          when :small, :sm
+            "gap-x-1.5 px-2.5 py-1.5 text-sm"
+          when :large, :lg
+            "gap-x-2 px-3.5 py-2.5 text-lg"
+          else # :medium, :md
+            "gap-x-1.5 px-3 py-2 text-base"
+          end
+        end
+
+        def variant_classes
+          case variant
+          when :primary
+            "bg-blue-600 text-white hover:bg-blue-700 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600"
+          when :secondary
+            "bg-white text-gray-900 ring-1 ring-inset ring-gray-300 hover:bg-gray-50"
+          when :success
+            "bg-green-600 text-white hover:bg-green-700 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-green-600"
+          when :danger
+            "bg-red-600 text-white hover:bg-red-700 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-red-600"
+          when :ghost
+            "bg-transparent text-gray-700 hover:bg-gray-100"
+          else # :default
+            "bg-gray-700 text-white hover:bg-gray-800 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-gray-700"
+          end
+        end
+      end
+    end
+  end
+end