skeleton-loader 0.1.0

data/app/javascript/client_skeleton_loader.js

@@ -0,0 +1,234 @@
+export default class ClientSkeletonLoader {
+  static loadingStates = new Map();
+  static activeSkeletons = new Map();
+
+  constructor() {
+    this.defaultDisplayStyles = {};
+    this.skeletonClass = 'skeleton-loader--client';
+    this.contentRefAttr = 'data-content-id';
+    this.apiEndpoint = '/skeleton_loader/templates';
+  }
+
+  /**
+   * Creates or retrieves a skeleton instance for a content element
+   */
+  getSkeletonInstance(contentId) {
+    if (!ClientSkeletonLoader.activeSkeletons.has(contentId)) {
+      ClientSkeletonLoader.activeSkeletons.set(contentId, this.createSkeletonInstance(contentId));
+    }
+    return ClientSkeletonLoader.activeSkeletons.get(contentId);
+  }
+
+  /**
+   * Creates a new skeleton instance
+   */
+  createSkeletonInstance(contentId) {
+    return {
+      isLoading: () => ClientSkeletonLoader.loadingStates.get(contentId) || false,
+      reveal: () => {
+        const skeletonElement = document.querySelector(`[${this.contentRefAttr}="${contentId}"]`);
+        const contentElement = document.getElementById(contentId);
+        if (skeletonElement && contentElement) {
+          this.revealContent(skeletonElement, contentElement);
+        }
+      }
+    };
+  }
+
+  /**
+   * Main render method that handles predefined skeletons
+   */
+  async render({ contentId, type = 'default', ...options } = {}) {
+    return this.processRender({
+      contentId,
+      mode: 'predefined',
+      type,
+      ...options
+    });
+  }
+
+  /**
+   * Custom render method for user-provided markup
+   */
+  async renderCustom({ contentId, markup } = {}) {
+    if (!markup) return this.logError('Custom markup is required');
+
+    return this.processRender({
+      contentId,
+      mode: 'custom',
+      markup
+    });
+  }
+
+  /**
+   * Core rendering logic shared between render methods
+   */
+  async processRender(params) {
+    const { contentId } = params;
+    if (!contentId) return this.logError('contentId is required');
+
+    const skeleton = this.getSkeletonInstance(contentId);
+    if (skeleton.isLoading()) {
+      console.warn(`Skeleton loading already in progress for ${contentId}`);
+      return skeleton;
+    }
+
+    try {
+      const content = await this.initializeLoading(contentId);
+      if (!content) return skeleton;
+
+      const skeletonElement = await this.createSkeletonElement(params);
+      if (skeletonElement) this.showSkeleton(skeletonElement, content);
+
+      return skeleton;
+    } catch (error) {
+      console.error('[SkeletonLoader] Render failed:', error);
+      return skeleton;
+    }
+  }
+
+  /**
+   * Initialize loading state and prepare content
+   */
+  async initializeLoading(contentId) {
+    ClientSkeletonLoader.loadingStates.set(contentId, true);
+    return this.hideContent(contentId);
+  }
+
+  /**
+   * Hides the content and stores its original display style
+   */
+  hideContent(contentId) {
+    const content = document.getElementById(contentId);
+    if (!content) {
+      console.error(`Content not found: #${contentId}`);
+      return null;
+    }
+    const displayStyle = getComputedStyle(content).display;
+
+    if (displayStyle !== 'none') {
+      this.defaultDisplayStyles[contentId] = displayStyle;
+    }
+    content.style.display = 'none';
+    return content;
+  }
+
+  /**
+   * Reveals the content and cleans up the skeleton
+   */
+  revealContent(skeleton, content) {
+    const contentId = content.id;
+    if (!ClientSkeletonLoader.loadingStates.get(contentId)) {
+      return;
+    }
+
+    skeleton.remove();
+    content.style.display = this.defaultDisplayStyles[contentId];
+    ClientSkeletonLoader.loadingStates.set(contentId, false);
+  }
+
+  /**
+   * Displays the skeleton by inserting it before the hidden content
+   */
+  showSkeleton(skeleton, content) {
+    this.clearPreviousSkeleton(content.id);
+    skeleton.setAttribute(this.contentRefAttr, content.id);
+    skeleton.style.display = 'block';
+    content.parentNode.insertBefore(skeleton, content);
+  }
+
+  /**
+   * Removes any existing skeleton associated with the content ID
+   */
+  clearPreviousSkeleton(contentId) {
+    const existingSkeletons = document.querySelectorAll(`[${this.contentRefAttr}="${contentId}"]`);
+    existingSkeletons.forEach(skeleton => skeleton.remove());
+  }
+
+  /**
+   * Creates a skeleton element by fetching the template
+   */
+  async createSkeletonElement({ contentId, mode, markup = null, type, ...options }) {
+    const params = this.buildParams({ contentId, mode, markup, type, ...options });
+    try {
+      const template = await this.fetchTemplate(params);
+      return this.parseTemplateToElement(template, contentId);
+    } catch (error) {
+      console.error('Error creating skeleton:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Fetches the skeleton template from the server
+   */
+  async fetchTemplate(params) {
+    const response = await fetch(`${this.apiEndpoint}?${params.toString()}`, {
+      method: 'GET',
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+    });
+
+    if (!response.ok) {
+      throw new Error('Failed to fetch skeleton template');
+    }
+
+    return response.text();
+  }
+
+  /**
+   * Converts a template string into a DOM element
+   */
+  parseTemplateToElement(template, contentId) {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(template, 'text/html');
+    const skeletonElement = doc.body.firstElementChild;
+
+    if (!skeletonElement) {
+      console.error(`Invalid skeleton template for contentId: ${contentId}`);
+      return null;
+    }
+    return skeletonElement;
+  }
+
+  /**
+   * Builds query parameters for fetching the skeleton template
+   */
+  buildParams({ contentId, mode, markup, type, ...options }) {
+    const params = new URLSearchParams({
+      content_id: contentId,
+      mode,
+      type: type || 'default',
+      ...this.formatOptions(options)
+    });
+
+    if (markup) params.set('markup', markup);
+    return params;
+  }
+
+  /**
+   * Format options to snake_case for Rails
+   */
+  formatOptions(options) {
+    return Object.fromEntries(
+      Object.entries(options).map(([key, value]) => [
+        this.toSnakeCase(key),
+        value
+      ])
+    );
+  }
+
+  /**
+   * Convert camelCase to snake_case
+   */
+  toSnakeCase(str) {
+    return str.replace(/([A-Z])/g, "_$1").toLowerCase();
+  }
+
+  /**
+   * Logs an error message and returns null
+   */
+  logError(message) {
+    console.error(`[SkeletonLoader] ${message}`);
+    return null;
+  }
+}

data/app/javascript/server_skeleton_loader.js

@@ -0,0 +1,113 @@
+export class ServerSkeletonLoader {
+  constructor() {
+    this.SKELETON_CLASS = 'skeleton-loader--server';
+    this.CONTENT_ID_ATTR = 'data-content-id';
+    this.contentsDisplayStyles = {};
+  }
+
+  // Instead of class fields, move static properties inside the class
+  static get SKELETON_CLASS() {
+    return 'skeleton-loader--server';
+  }
+
+  static get CONTENT_ID_ATTR() {
+    return 'data-content-id';
+  }
+
+  // ============= PUBLIC API =============
+
+  // Start the loader and initialize event listeners
+  start() {
+    this.setupInitialLoading();
+    this.setupContentsSwap();
+    return this;
+  }
+
+  // ============= CORE PROCESSING =============
+
+  // Setup initial loading states for skeletons on DOM load
+  setupInitialLoading() {
+    document.addEventListener('DOMContentLoaded', () => {
+      this.captureContentsDisplayStyles();
+      this.hideContents();
+      this.showSkeletons();
+    });
+  }
+
+  // Swap skeletons with content on full page load
+  setupContentsSwap() {
+    window.addEventListener('load', async() => await this.revealContent());
+  }
+
+  // ============= CONTENT MANAGEMENT =============
+
+  // Store the original display styles of content elements for later restoration
+  captureContentsDisplayStyles() {
+    const skeletons = document.querySelectorAll(`.${ServerSkeletonLoader.SKELETON_CLASS}`);
+    skeletons.forEach(skeleton => {
+      const contentId = skeleton.getAttribute(ServerSkeletonLoader.CONTENT_ID_ATTR);
+      const content = document.getElementById(contentId);
+
+      if (content) {
+        const originalDisplay = getComputedStyle(content).display || 'block';
+        this.contentsDisplayStyles[contentId] = originalDisplay;
+      } else {
+        console.warn(`Content element with id "${contentId}" not found`);
+      }
+    });
+  }
+
+  // Show skeleton loading elements by setting their display property
+  showSkeletons() {
+    const skeletons = document.querySelectorAll(`.${ServerSkeletonLoader.SKELETON_CLASS}`);
+    skeletons.forEach(skeleton => {
+      skeleton.style.display = 'block';
+    });
+  }
+
+  // Reveal content by swapping skeletons with actual content elements
+  async revealContent() {
+    this.hideSkeletons();
+    this.showContents();
+  }
+
+  // Hide skeleton loading elements once content is ready to be shown
+  hideSkeletons() {
+    const skeletons = document.querySelectorAll(`.${ServerSkeletonLoader.SKELETON_CLASS}`);
+    skeletons.forEach(skeleton => {
+      skeleton.style.display = 'none';
+    });
+  }
+
+  // Display actual content elements by restoring their original display styles
+  showContents() {
+    const skeletons = document.querySelectorAll(`.${ServerSkeletonLoader.SKELETON_CLASS}`);
+    skeletons.forEach(skeleton => {
+      const contentId = skeleton.getAttribute(ServerSkeletonLoader.CONTENT_ID_ATTR);
+      const content = document.getElementById(contentId);
+
+      if (content) {
+        const originalDisplay = this.contentsDisplayStyles[contentId] || 'block';
+        content.style.display = originalDisplay;
+        content.style.visibility = 'visible'; // Ensure content is visible
+      } else {
+        console.warn(`Content element with id "${contentId}" not found`);
+      }
+    });
+  }
+
+  // Hide content elements initially to be replaced with skeleton loaders
+  hideContents() {
+    const skeletons = document.querySelectorAll(`.${ServerSkeletonLoader.SKELETON_CLASS}`);
+    skeletons.forEach(skeleton => {
+      const contentId = skeleton.getAttribute(ServerSkeletonLoader.CONTENT_ID_ATTR);
+      const content = document.getElementById(contentId);
+
+      if (content) {
+        content.style.display = 'none';
+      } else {
+        console.warn(`Content element with id "${contentId}" not found`);
+      }
+    });
+  }
+}

data/app/javascript/skeleton_loader.js

@@ -0,0 +1,6 @@
+import ClientSkeletonLoader from './client_skeleton_loader'
+import { ServerSkeletonLoader } from './server_skeleton_loader'
+
+new ServerSkeletonLoader().start()
+
+export default ClientSkeletonLoader

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+SkeletonLoader::Engine.routes.draw do
+  get "templates", to: "skeleton_loader#show"
+end

data/lib/generators/skeleton_loader/add_templates_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SkeletonLoader
+  module Generators
+    # Copies default templates to app/views/skeleton_loader and
+    # creates the necessary initializer file.
+    class AddTemplatesGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs SkeletonLoader default templates"
+
+      def add_templates
+        directory ".", "app/views/skeleton_loader"
+      end
+    end
+  end
+end

data/lib/generators/skeleton_loader/reset_templates_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SkeletonLoader
+  module Generators
+    # Forces overwrite of any customized templates in app/views/skeleton_loader
+    # with the original default versions.
+    class ResetTemplatesGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Resets SkeletonLoader templates to default"
+
+      def reset_templates
+        directory ".", "app/views/skeleton_loader", force: true
+      end
+    end
+  end
+end

data/lib/generators/skeleton_loader/templates/_card.html.erb

@@ -0,0 +1,31 @@
+<%
+  total_width = (@width * @per_row) + (16 * (@per_row - 1))
+  scaled_width = total_width * @scale
+%>
+
+<div id="f1" class="skeleton-card" style="padding: <%= 16 * @scale %>px;">
+  <div id="f2" style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 16 * @scale %>px;
+    width: <%= scaled_width %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div id="f3" style="width: 100%;">
+        <div id="f4" class="skeleton-loading <%= @animation_type %>" style="
+        height: <%= 240 * @scale %>px;
+          margin-bottom: <%= 16 * @scale %>px;
+        "></div>
+        <div id="f5" class="skeleton-loading <%= @animation_type %>" style="
+        height: <%= 20 * @scale %>px;
+          width: 50%;
+          margin-bottom: <%= 8 * @scale %>px;
+        "></div>
+        <div class="skeleton-loading <%= @animation_type %>" style="
+        height: <%= 20 * @scale %>px;
+          width: 30%;
+        "></div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/lib/generators/skeleton_loader/templates/_comment.html.erb

@@ -0,0 +1,61 @@
+<%
+  total_width = (@width * @per_row) + (16 * (@per_row - 1))
+  scaled_width = total_width * @scale
+%>
+
+<div class="skeleton-comments" style="padding: <%= 16 * @scale %>px;">
+  <div style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 16 * @scale %>px;
+    width: <%= scaled_width %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div class="skeleton-comment" style="width: 100%;">
+        <div style="
+        display: flex;
+          align-items: flex-start;
+          gap: <%= 16 * @scale %>px;
+        ">
+          <!-- Avatar circle -->
+          <div class="skeleton-loading <%= @animation_type %>" style="
+          border-radius: 50%;
+            height: <%= 48 * @scale %>px;
+            width: <%= 48 * @scale %>px;
+            flex-shrink: 0;
+          "></div>
+
+          <!-- Content area -->
+          <div style="flex: 1;">
+            <!-- Username -->
+            <div class="skeleton-loading <%= @animation_type %>" style="
+            height: <%= 16 * @scale %>px;
+              width: 25%;
+              margin-bottom: <%= 8 * @scale %>px;
+            "></div>
+
+            <!-- Comment text lines -->
+            <div style="
+            display: flex;
+              flex-direction: column;
+              gap: <%= 8 * @scale %>px;
+            ">
+              <div class="skeleton-loading <%= @animation_type %>" style="
+              height: <%= 16 * @scale %>px;
+                width: 100%;
+              "></div>
+              <div class="skeleton-loading <%= @animation_type %>" style="
+              height: <%= 16 * @scale %>px;
+                width: 83%;
+              "></div>
+              <div class="skeleton-loading <%= @animation_type %>" style="
+              height: <%= 16 * @scale %>px;
+                width: 67%;
+              "></div>
+            </div>
+          </div>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/lib/generators/skeleton_loader/templates/_default.html.erb

@@ -0,0 +1,23 @@
+<%
+  total_width = (@width * @per_row) + (16 * (@per_row - 1))
+  scaled_width = total_width * @scale
+%>
+
+<div class="skeleton-default" style="
+padding: <%= 16 * @scale %>px;
+  width: <%= scaled_width %>px;
+">
+  <div style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 16 * @scale %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div style="display: flex; flex-direction: column; gap: <%= 10 * @scale %>px;">
+        <div class="skeleton-loading <%= @animation_type %>" style="height: <%= 26 * @scale %>px; width: 75%;"></div>
+        <div class="skeleton-loading <%= @animation_type %>" style="height: <%= 128 * @scale %>px; width: 100%;"></div>
+        <div class="skeleton-loading <%= @animation_type %>" style="height: <%= 16 * @scale %>px; width: 50%;"></div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/lib/generators/skeleton_loader/templates/_gallery.html.erb

@@ -0,0 +1,19 @@
+<%
+  total_width = (@width * @per_row) + (16 * (@per_row - 1))
+  scaled_width = total_width * @scale
+%>
+
+<div class="skeleton-gallery" style="
+padding: <%= 16 * @scale %>px;
+  width: <%= scaled_width %>px;
+">
+  <div style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 16 * @scale %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div class="skeleton-loading <%= @animation_type %>" style="padding-bottom: 100%;"></div>
+    <% end %>
+  </div>
+</div>

data/lib/generators/skeleton_loader/templates/_paragraph.html.erb

@@ -0,0 +1,28 @@
+<%
+  Rails.logger.debug("FFFFFFF")
+  Rails.logger.debug(@width)
+  Rails.logger.debug(@per_row)
+  Rails.logger.debug(@count)
+  total_width = (@width * @per_row) + (16 * (@per_row - 1))
+  scaled_width = total_width * @scale
+%>
+
+<div class="skeleton-paragraph" style="display:inline-block; padding: <%= 16 * @scale %>px;">
+  <div style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 24 * @scale %>px;
+    width: <%= scaled_width %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div style="display: flex; flex-direction: column; gap: <%= 12 * @scale %>px;">
+        <% 4.times do |i| %>
+          <div class="skeleton-loading <%= @animation_type %>" style="
+          height: <%= 20 * @scale %>px;
+            width: <%= [100, 83, 67, 75][i % 4] %>%;
+          "></div>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+</div>

data/lib/generators/skeleton_loader/templates/_product.html.erb

@@ -0,0 +1,49 @@
+<%
+  total_width = (@width * @per_row) + (24 * (@per_row - 1))
+
+  # Apply container scale
+  scaled_width = total_width * @scale
+%>
+
+<div class="skeleton-product" style="
+width: <%= scaled_width %>px;
+  padding: <%= 16 * @scale %>px;
+">
+  <div style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 16 * @scale %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div style="display: flex; flex-direction: column;">
+        <!-- Main image area -->
+        <div class="skeleton-loading <%= @animation_type %>" style="
+        height: <%= 256 * @scale %>px;
+          width: 100%;
+          margin-bottom: <%= 16 * @scale %>px;
+        "></div>
+
+        <!-- Content area -->
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: <%= 12 * @scale %>px;">
+          <div style="width: 100%; display: flex; flex-direction: column; gap: <%= 12 * @scale %>px;">
+            <div class="skeleton-loading <%= @animation_type %>" style="
+            height: <%= 20 * @scale %>px;
+              width: 50%;
+            "></div>
+
+            <div class="skeleton-loading <%= @animation_type %>" style="
+            height: <%= 14 * @scale %>px;
+              width: 66%;
+            "></div>
+          </div>
+
+          <!-- Price area -->
+          <div class="skeleton-loading <%= @animation_type %>" style="
+          height: <%= 24 * @scale %>px;
+            width: 25%;
+          "></div>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/lib/generators/skeleton_loader/templates/_profile.html.erb

@@ -0,0 +1,28 @@
+<%
+  total_width = (@width * @per_row) + (16 * (@per_row - 1))
+  scaled_width = total_width * @scale
+%>
+
+<div class="skeleton-user-profile" style="padding: <%= 16 * @scale %>px;">
+  <div style="
+  display: grid;
+    grid-template-columns: repeat(<%= @per_row %>, <%= @width * @scale %>px);
+    gap: <%= 16 * @scale %>px;
+    width: <%= scaled_width %>px;
+  ">
+    <% @count.to_i.times do %>
+      <div style="display: flex; gap: <%= 16 * @scale %>px;">
+        <div class="skeleton-loading <%= @animation_type %>" style="
+        width: <%= 128 * @scale %>px;
+          height: <%= 128 * @scale %>px;
+          flex-shrink: 0;
+        "></div>
+        <div style="flex-grow: 1;">
+          <div class="skeleton-loading <%= @animation_type %>" style="height: <%= 16 * @scale %>px; width: 75%; margin-bottom: <%= 12 * @scale %>px;"></div>
+          <div class="skeleton-loading <%= @animation_type %>" style="height: <%= 16 * @scale %>px; width: 50%; margin-bottom: <%= 12 * @scale %>px;"></div>
+          <div class="skeleton-loading <%= @animation_type %>" style="height: <%= 16 * @scale %>px; width: 25%;"></div>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/lib/skeleton-loader.rb

@@ -0,0 +1,7 @@
+# rubocop:disable Naming/FileName
+# frozen_string_literal: true
+
+# Bridge file, redirects to `skeleton_loader.rb`
+require_relative "skeleton_loader"
+
+# rubocop:enable Naming/FileName