Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

[67472] Document SkeletonBox and Spinner compeontns as loading pattern (#20336)

Henriette Darge49c1db84ac4b
diff --git a/lookbook/docs/components/loading-indicators.md.erb b/lookbook/docs/components/loading-indicators.md.erb
new file mode 100644
index 00000000000..f5c76f03cb8
--- /dev/null
+++ b/lookbook/docs/components/loading-indicators.md.erb
@@ -0,0 +1,62 @@
+This document describes the available loading indicators in our application and outlines when and how to use them appropriately.
+
+Currently supported loading components:
+
+- `Primer::Alpha::SkeletonBox`
+- `Primer::Beta::Spinner`
+- `LoadingIndicator` ⚠️ **Deprecated**
+
+---
+
+## SkeletonBox
+
+### Description
+
+`SkeletonBox` displays a rectangular placeholder with a subtle shimmering animation moving from left to right. Width and height can be configured. Multiple `SkeletonBox` elements can be arranged side-by-side or stacked vertically.
+
+This component is ideal for visually representing the structure of content that is currently loading.
+
+<%= embed OpenProject::Common::LoadingIndicatorsPreview, :skeleton_box %>
+
+### When to Use
+
+Use `SkeletonBox` when:
+
+- You know the approximate layout of the content to be loaded.
+- You want to avoid layout shifts after content loads.
+- You're loading a larger block of content (e.g., cards, list items, sections).
+
+### Example Use Case
+
+* Loading activity entries in the activity tab
+* Loading the notifications in notification center
+
+## Spinner
+
+### Description
+
+`Spinner` is a small circular loading indicator with a continuous spinning animation.
+
+<%= embed OpenProject::Common::LoadingIndicatorsPreview, :spinner %>
+
+### When to Use
+
+Use `Spinner` when:
+
+- The content being loaded is bound within a small container
+- The content layout is not known at all
+- You're waiting for a server response without a visual response to show (eg. content will not be replaced)
+
+### Example Use Case
+
+* Use a Spinner inside a search input field while fetching suggestions from the server.
+
+### LoadingIndicator (Deprecated)
+
+⚠️ **Do not use** ⚠️
+
+<%= embed OpenProject::Deprecated::LoadingIndicatorPreview, :default %>
+
+The LoadingIndicator component was implemented in Angular and is now considered deprecated.
+
+It does not conform to current design or technical standards. All usages should be replaced with either `SkeletonBox` or `Spinner` depending on context.
diff --git a/lookbook/previews/op_primer/inset_box_component_preview.rb b/lookbook/previews/op_primer/inset_box_component_preview.rb
index ab5a52c4b49..e20f58c6c0a 100644
--- a/lookbook/previews/op_primer/inset_box_component_preview.rb
+++ b/lookbook/previews/op_primer/inset_box_component_preview.rb
@@ -29,6 +29,7 @@
#++
module OpPrimer
+ # @logical_path OpenProject/Primer
class InsetBoxComponentPreview < ViewComponent::Preview
def default
render OpPrimer::InsetBoxComponent.new do
diff --git a/lookbook/previews/open_project/common/loading_indicators_preview.rb b/lookbook/previews/open_project/common/loading_indicators_preview.rb
new file mode 100644
index 00000000000..b328fd32a9a
--- /dev/null
+++ b/lookbook/previews/open_project/common/loading_indicators_preview.rb
@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+module OpenProject
+ module Common
+ # @hidden
+ class LoadingIndicatorsPreview < Lookbook::Preview
+ # @label SkeletonBox
+ def skeleton_box
+ render_with_template
+ end
+
+ # @label Spinner
+ def spinner
+ render(Primer::Beta::Spinner.new)
+ end
+ end
+ end
+end
diff --git a/lookbook/previews/open_project/common/loading_indicators_preview/skeleton_box.html.erb b/lookbook/previews/open_project/common/loading_indicators_preview/skeleton_box.html.erb
new file mode 100644
index 00000000000..358a131c0ed
--- /dev/null
+++ b/lookbook/previews/open_project/common/loading_indicators_preview/skeleton_box.html.erb
@@ -0,0 +1,9 @@
+<%=
+ render(Primer::Alpha::SkeletonBox.new(width: "200px", height: "32px", mb: 2))
+%>
+<%=
+ render(Primer::Alpha::SkeletonBox.new(width: "100px", height: "32px", mb: 2))
+%>
+<%=
+ render(Primer::Alpha::SkeletonBox.new(width: "150px", height: "32px"))
+%>
diff --git a/lookbook/previews/open_project/common/loading_indicator_preview.rb b/lookbook/previews/open_project/deprecated/loading_indicator_preview.rb
similarity index 95%
rename from lookbook/previews/open_project/common/loading_indicator_preview.rb
rename to lookbook/previews/open_project/deprecated/loading_indicator_preview.rb
index 3b978189384..ca535fe7cfa 100644
--- a/lookbook/previews/open_project/common/loading_indicator_preview.rb
+++ b/lookbook/previews/open_project/deprecated/loading_indicator_preview.rb
@@ -29,8 +29,8 @@
#++
module OpenProject
- module Common
- # @logical_path OpenProject/Common
+ module Deprecated
+ # @logical_path OpenProject/deprecated
class LoadingIndicatorPreview < Lookbook::Preview
def default; end
end
diff --git a/lookbook/previews/open_project/common/loading_indicator_preview/default.html.erb b/lookbook/previews/open_project/deprecated/loading_indicator_preview/default.html.erb
similarity index 100%
rename from lookbook/previews/open_project/common/loading_indicator_preview/default.html.erb
rename to lookbook/previews/open_project/deprecated/loading_indicator_preview/default.html.erb