Skip to content

A platform for community discussion. Free, open, simple.

UX: Move the styleguide navigation into the main sidebar (#42058)

Sérgio Saquetim1506fcaec208
diff --git a/plugins/styleguide/assets/javascripts/discourse/components/styleguide-link.gjs b/plugins/styleguide/assets/javascripts/discourse/components/styleguide-link.gjs
deleted file mode 100644
index 5aa30bf7072..00000000000
--- a/plugins/styleguide/assets/javascripts/discourse/components/styleguide-link.gjs
+++ /dev/null
@@ -1,14 +0,0 @@
-import { array } from "@ember/helper";
-import { LinkTo } from "@ember/routing";
-import sectionTitle from "discourse/plugins/styleguide/discourse/helpers/section-title";
-
-const StyleguideLink = <template>
- <LinkTo
- @route="styleguide.show"
- @models={{array @section.category @section.id}}
- >
- {{sectionTitle @section.id}}
- </LinkTo>
-</template>;
-
-export default StyleguideLink;
diff --git a/plugins/styleguide/assets/javascripts/discourse/components/styleguide-section.gjs b/plugins/styleguide/assets/javascripts/discourse/components/styleguide-section.gjs
index 157b1b4a5b5..e4c2a95c68e 100644
--- a/plugins/styleguide/assets/javascripts/discourse/components/styleguide-section.gjs
+++ b/plugins/styleguide/assets/javascripts/discourse/components/styleguide-section.gjs
@@ -2,8 +2,11 @@
import Component from "@ember/component";
import { computed } from "@ember/object";
import { tagName } from "@ember-decorators/component";
+import DBreadcrumbsItem from "discourse/ui-kit/d-breadcrumbs-item";
+import DPageHeader from "discourse/ui-kit/d-page-header";
import dConcatClass from "discourse/ui-kit/helpers/d-concat-class";
import { i18n } from "discourse-i18n";
+import ToggleColorMode from "discourse/plugins/styleguide/discourse/components/toggle-color-mode";
import sectionTitle from "discourse/plugins/styleguide/discourse/helpers/section-title";
@tagName("")
@@ -20,18 +23,47 @@ export default class StyleguideSection extends Component {
}
}
+ // Built by hand rather than with a route, because a breadcrumb item can only link to a route
+ // without dynamic segments and this one needs the category and section.
+ @computed("section")
+ get sectionPath() {
+ if (this.section) {
+ return `/styleguide/${this.section.category}/${this.section.id}`;
+ }
+ }
+
<template>
<section
class={{dConcatClass "styleguide-section" this.sectionClass}}
...attributes
>
- <h1 class="section-title">
- {{#if this.section}}
- {{sectionTitle this.section.id}}
- {{else}}
- {{i18n this.title}}
- {{/if}}
- </h1>
+ <DPageHeader @hideTabs={{true}}>
+ <:breadcrumbs>
+ <DBreadcrumbsItem
+ @path="/styleguide"
+ @label={{i18n "styleguide.title"}}
+ />
+
+ {{#if this.section}}
+ <DBreadcrumbsItem
+ @path={{this.sectionPath}}
+ @label={{sectionTitle this.section.id}}
+ />
+ {{/if}}
+
+ {{! Color mode is page chrome rather than an action on this page, so it sits on the
+ utility row with the breadcrumb instead of beside the title. }}
+ <ToggleColorMode />
+ </:breadcrumbs>
+
+ <:title>
+ {{#if this.section}}
+ {{sectionTitle this.section.id}}
+ {{else if this.title}}
+ {{i18n this.title}}
+ {{/if}}
+ </:title>
+ </DPageHeader>
<div class="styleguide-section-contents">
{{yield}}
diff --git a/plugins/styleguide/assets/javascripts/discourse/components/toggle-color-mode.gjs b/plugins/styleguide/assets/javascripts/discourse/components/toggle-color-mode.gjs
index 17be3b8bf2b..8e3984eada8 100644
--- a/plugins/styleguide/assets/javascripts/discourse/components/toggle-color-mode.gjs
+++ b/plugins/styleguide/assets/javascripts/discourse/components/toggle-color-mode.gjs
@@ -1,46 +1,72 @@
import Component from "@glimmer/component";
import { tracked } from "@glimmer/tracking";
+import { fn } from "@ember/helper";
import { action } from "@ember/object";
import { service } from "@ember/service";
+import DMenu from "discourse/float-kit/components/d-menu";
import { loadColorSchemeStylesheet } from "discourse/lib/color-scheme-picker";
import { currentThemeId } from "discourse/lib/theme-selector";
import DButton from "discourse/ui-kit/d-button";
+import DDropdownMenu from "discourse/ui-kit/d-dropdown-menu";
+import { i18n } from "discourse-i18n";
const DARK = "dark";
const LIGHT = "light";
+const AUTO = "auto";
-function colorSchemeOverride(type) {
- const lightScheme = document.querySelector("link.light-scheme");
- const darkScheme =
+const AUTO_LIGHT_MEDIA = "(prefers-color-scheme: light)";
+const AUTO_DARK_MEDIA = "(prefers-color-scheme: dark)";
+
+const ICONS = {
+ [LIGHT]: "sun",
+ [DARK]: "moon",
+ [AUTO]: "circle-half-stroke",
+};
+
+function lightSchemeStylesheet() {
+ return document.querySelector("link.light-scheme");
+}
+
+function darkSchemeStylesheet() {
+ return (
document.querySelector("link.dark-scheme") ||
- document.querySelector("link#cs-preview-dark");
+ document.querySelector("link#cs-preview-dark")
+ );
+}
+
+/** The mode the document is currently showing, which outlives any one instance of this component. */
+function appliedColorMode() {
+ if (darkSchemeStylesheet()?.media === "all") {
+ return DARK;
+ }
- if (!lightScheme && !darkScheme) {
+ if (lightSchemeStylesheet()?.media === "all") {
+ return LIGHT;
+ }
+
+ return AUTO;
+}
+
+function applyColorMode(mode) {
+ const lightScheme = lightSchemeStylesheet();
+ const darkScheme = darkSchemeStylesheet();
+
+ if (!lightScheme || !darkScheme) {
return;
}
- switch (type) {
+ switch (mode) {
case DARK:
- lightScheme.origMedia = lightScheme.media;
lightScheme.media = "none";
- darkScheme.origMedia = darkScheme.media;
darkScheme.media = "all";
break;
case LIGHT:
- lightScheme.origMedia = lightScheme.media;
lightScheme.media = "all";
- darkScheme.origMedia = darkScheme.media;
darkScheme.media = "none";
break;
default:
- if (lightScheme.origMedia) {
- lightScheme.media = lightScheme.origMedia;
- lightScheme.removeAttribute("origMedia");
- }
- if (darkScheme.origMedia) {
- darkScheme.media = darkScheme.origMedia;
- darkScheme.removeAttribute("origMedia");
- }
+ lightScheme.media = AUTO_LIGHT_MEDIA;
+ darkScheme.media = AUTO_DARK_MEDIA;
break;
}
}
@@ -48,7 +74,9 @@ function colorSchemeOverride(type) {
export default class ToggleColorMode extends Component {
@service site;
- @tracked colorSchemeOverride = this.default;
+ // Seeded from the document rather than from a preference, because this component is rebuilt on
+ // every styleguide navigation while the mode it applied stays on the page.
+ @tracked mode = appliedColorMode();
@tracked shouldRender = true;
constructor() {
@@ -70,21 +98,70 @@ export default class ToggleColorMode extends Component {
}
}
- get default() {
- return window.matchMedia("(prefers-color-scheme: dark)").matches
- ? DARK
- : LIGHT;
+ get icon() {
+ return ICONS[this.mode];
}
@action
- toggle() {
- this.colorSchemeOverride = this.colorSchemeOverride === DARK ? LIGHT : DARK;
- colorSchemeOverride(this.colorSchemeOverride);
+ select(mode, dMenu) {
+ applyColorMode(mode);
+
+ // Read back rather than assume: with the dark stylesheet still loading nothing was applied,
+ // and the trigger has to keep showing the mode that is actually on screen.
+ this.mode = appliedColorMode();
+ dMenu.close();
}
<template>
{{#if this.shouldRender}}
- <DButton @action={{this.toggle}} class="toggle-color-mode">Toggle color</DButton>
+ <DMenu
+ @icon={{this.icon}}
+ @identifier="styleguide-color-mode"
+ @animated={{false}}
+ @title={{i18n "sidebar.footer.interface_color_selector.title"}}
+ @ariaLabel={{i18n
+ "sidebar.footer.interface_color_selector.aria_label"
+ mode=this.mode
+ }}
+ @triggerClass="btn-default btn-small"
+ class="toggle-color-mode"
+ data-current-mode={{this.mode}}
+ >
+ <:content as |dMenu|>
+ <DDropdownMenu as |dropdown|>
+ <dropdown.item>
+ <DButton
+ class="toggle-color-mode__light-option"
+ @icon="sun"
+ @translatedLabel={{i18n
+ "sidebar.footer.interface_color_selector.light"
+ }}
+ @action={{fn this.select LIGHT dMenu}}
+ />
+ </dropdown.item>
+ <dropdown.item>
+ <DButton
+ class="toggle-color-mode__dark-option"
+ @icon="moon"
+ @translatedLabel={{i18n
+ "sidebar.footer.interface_color_selector.dark"
+ }}
+ @action={{fn this.select DARK dMenu}}
+ />
+ </dropdown.item>
+ <dropdown.item>
+ <DButton
+ class="toggle-color-mode__auto-option"
+ @icon="circle-half-stroke"
+ @translatedLabel={{i18n
+ "sidebar.footer.interface_color_selector.auto"
+ }}
+ @action={{fn this.select AUTO dMenu}}
+ />
+ </dropdown.item>
+ </DDropdownMenu>
+ </:content>
+ </DMenu>
{{/if}}
</template>
}
diff --git a/plugins/styleguide/assets/javascripts/discourse/controllers/styleguide.js b/plugins/styleguide/assets/javascripts/discourse/controllers/styleguide.js
deleted file mode 100644
index 30d43970834..00000000000
--- a/plugins/styleguide/assets/javascripts/discourse/controllers/styleguide.js
+++ /dev/null
@@ -1,5 +0,0 @@
-import Controller from "@ember/controller";
-
-export default class Styleguide extends Controller {
- sections = null;
-}
diff --git a/plugins/styleguide/assets/javascripts/discourse/initializers/styleguide-sidebar.js b/plugins/styleguide/assets/javascripts/discourse/initializers/styleguide-sidebar.js
new file mode 100644
index 00000000000..86357b316a3
--- /dev/null
+++ b/plugins/styleguide/assets/javascripts/discourse/initializers/styleguide-sidebar.js
@@ -0,0 +1,12 @@
+import { withPluginApi } from "discourse/lib/plugin-api";
+import styleguideSidebarPanelBuilder from "../lib/styleguide-sidebar-panel";
+
+export default {
+ name: "styleguide-sidebar",
+
+ initialize() {
+ withPluginApi((api) => {
+ api.addSidebarPanel(styleguideSidebarPanelBuilder);
+ });
+ },
+};
diff --git a/plugins/styleguide/assets/javascripts/discourse/lib/styleguide-sidebar-panel.js b/plugins/styleguide/assets/javascripts/discourse/lib/styleguide-sidebar-panel.js
new file mode 100644
index 00000000000..dcd8660b014
--- /dev/null
+++ b/plugins/styleguide/assets/javascripts/discourse/lib/styleguide-sidebar-panel.js
@@ -0,0 +1,102 @@
+import { cached } from "@glimmer/tracking";
+import BaseCustomSidebarSection from "discourse/lib/sidebar/base-custom-sidebar-section";
+import BaseCustomSidebarSectionLink from "discourse/lib/sidebar/base-custom-sidebar-section-link";
+import { i18n } from "discourse-i18n";
+import { STYLEGUIDE_PANEL } from "../services/styleguide-sidebar";
+import { allCategories } from "./styleguide";
+
+function categoryTitle(categoryId) {
+ return i18n(`styleguide.categories.${categoryId}`);
+}
+
+function sectionTitle(sectionId) {
+ return i18n(`styleguide.sections.${sectionId.replace(/-/g, "_")}.title`);
+}
+
+class StyleguideSectionLink extends BaseCustomSidebarSectionLink {
+ #section;
+
+ constructor({ section }) {
+ super(...arguments);
+ this.#section = section;
+ }
+
+ get name() {
+ return `${STYLEGUIDE_PANEL}-section-${this.#section.id}`;
+ }
+
+ get route() {
+ return "styleguide.show";
+ }
+
+ get models() {
+ return [this.#section.category, this.#section.id];
+ }
+
+ get text() {
+ return sectionTitle(this.#section.id);
+ }
+
+ get title() {
+ return this.text;
+ }
+
+ get keywords() {
+ // Consulted by the panel filter, which indexes on whole words. The id earns its place
+ // because a dasherized id is often what someone types when the title reads differently.
+ return {
+ navigation: [...this.text.toLowerCase().split(/\s+/), this.#section.id],
+ };
+ }
+}
+
+function buildCategorySection(category) {
+ return class StyleguideCategorySection extends BaseCustomSidebarSection {
+ get name() {
+ return `${STYLEGUIDE_PANEL}-category-${category.id}`;
+ }
+
+ get text() {
+ return categoryTitle(category.id);
+ }
+
+ get title() {
+ return this.text;
+ }
+
+ get links() {
+ return category.sections.map(
+ (section) => new StyleguideSectionLink({ section })
+ );
+ }
+ };
+}
+
+/**
+ * The styleguide's own navigation, rendered as a sidebar panel so it can replace the forum
+ * sidebar rather than sit beside it.
+ *
+ * Sections are built in a getter rather than registered up front, for two reasons. The section
+ * list is only complete once every initializer has had its chance to call `addStyleguideSection`,
+ * and `allCategories` memoizes on its first call — so reading it early would freeze a list that
+ * is still missing entries. Deferring to render time also means no re-registration dance is
+ * needed to get the panel to redraw.
+ */
+const styleguideSidebarPanelBuilder = (BaseCustomSidebarPanel) =>
+ class StyleguideSidebarPanel extends BaseCustomSidebarPanel {
+ key = STYLEGUIDE_PANEL;
+ hidden = true;
+ displayHeader = true;
+ expandActiveSection = true;
+ scrollActiveLinkIntoView = true;
+ filterable = true;
+
+ // The sidebar builds a fresh section instance from each of these classes on every render,
+ // so caching keeps that from rebuilding the classes themselves as well.
+ @cached
+ get sections() {
+ return allCategories().map(buildCategorySection);
+ }
+ };
+
+export default styleguideSidebarPanelBuilder;
diff --git a/plugins/styleguide/assets/javascripts/discourse/routes/styleguide.js b/plugins/styleguide/assets/javascripts/discourse/routes/styleguide.js
index 5977bfe1fb9..492cb0b9b52 100644
--- a/plugins/styleguide/assets/javascripts/discourse/routes/styleguide.js
+++ b/plugins/styleguide/assets/javascripts/discourse/routes/styleguide.js
@@ -1,14 +1,21 @@
import Route from "@ember/routing/route";
+import { service } from "@ember/service";
import loadFaker from "discourse/lib/load-faker";
import { allCategories } from "discourse/plugins/styleguide/discourse/lib/styleguide";
export default class Styleguide extends Route {
+ @service styleguideSidebar;
+
async model() {
await loadFaker(); // So that it can be used synchronously in styleguide components
return allCategories();
}
- setupController(controller, categories) {
- controller.set("categories", categories);
+ activate() {
+ this.styleguideSidebar.showSidebar();
+ }
+
+ deactivate() {
+ this.styleguideSidebar.hideSidebar();
}
}
diff --git a/plugins/styleguide/assets/javascripts/discourse/routes/styleguide/show.js b/plugins/styleguide/assets/javascripts/discourse/routes/styleguide/show.js
index 8c030b8da14..b647a6a279f 100644
--- a/plugins/styleguide/assets/javascripts/discourse/routes/styleguide/show.js
+++ b/plugins/styleguide/assets/javascripts/discourse/routes/styleguide/show.js
@@ -1,10 +1,20 @@
import Route from "@ember/routing/route";
+import { service } from "@ember/service";
import { createData } from "discourse/plugins/styleguide/discourse/lib/dummy-data";
import { sectionById } from "discourse/plugins/styleguide/discourse/lib/styleguide";
export default class StyleguideShow extends Route {
+ @service router;
+
model(params) {
- return sectionById(params.section);
+ const section = sectionById(params.section);
+
+ if (!section) {
+ this.router.replaceWith("/404");
+ return;
+ }
+
+ return section;
}
setupController(controller, section) {
diff --git a/plugins/styleguide/assets/javascripts/discourse/services/styleguide-sidebar.js b/plugins/styleguide/assets/javascripts/discourse/services/styleguide-sidebar.js
new file mode 100644
index 00000000000..e024b3ab5e8
--- /dev/null
+++ b/plugins/styleguide/assets/javascripts/discourse/services/styleguide-sidebar.js
@@ -0,0 +1,50 @@
+import Service, { service } from "@ember/service";
+import { MAIN_PANEL } from "discourse/lib/sidebar/panels";
+
+export const STYLEGUIDE_PANEL = "styleguide";
+
+/**
+ * Hands the main sidebar over to the styleguide's own navigation while the user is inside the
+ * styleguide, and gives it back on the way out.
+ *
+ * The styleguide used to render a second nav column of its own beside Discourse's, which cost a
+ * third of the viewport and showed forum navigation nobody needs while reading component docs.
+ * Taking over the one sidebar is the same trade the admin area and the docs plugin already make.
+ */
+export default class StyleguideSidebarService extends Service {
+ @service sidebarState;
+
+ showSidebar() {
+ // Order matters: `setSeparatedMode` turns the switch buttons back on, so hiding them has to
+ // come after it, and both have to come after the panel is current.
+ this.sidebarState.setPanel(STYLEGUIDE_PANEL);
+ this.sidebarState.setSeparatedMode();
+ this.sidebarState.hideSwitchPanelButtons();
+
+ // Renders the sidebar even for a reader whose navigation preference is the header dropdown.
+ // The styleguide's nav was unconditional before this, so losing it on a preference would be
+ // a regression rather than that preference being honored.
+ this.sidebarState.isForcingSidebar = true;
+ this.sidebarState.forcingSidebarPanel = STYLEGUIDE_PANEL;
+ }
+
+ hideSidebar() {
+ // Only unwind what this service actually set. Another feature may have taken the sidebar
+ // during the same transition, and clearing its claim would strand it.
+ if (this.sidebarState.forcingSidebarPanel !== STYLEGUIDE_PANEL) {
+ return;
+ }
+
+ if (this.#isVisible) {
+ this.sidebarState.setPanel(MAIN_PANEL);
+ }
+
+ this.sidebarState.isForcingSidebar = false;
+ this.sidebarState.forcingSidebarPanel = null;
+ }
+
+ /** Whether the styleguide panel is still the one on screen. */
+ get #isVisible() {
+ return this.sidebarState.currentPanel?.key === STYLEGUIDE_PANEL;
+ }
+}
diff --git a/plugins/styleguide/assets/javascripts/discourse/templates/styleguide.gjs b/plugins/styleguide/assets/javascripts/discourse/templates/styleguide.gjs
index fd00ecb5d51..fb07cd57d49 100644
--- a/plugins/styleguide/assets/javascripts/discourse/templates/styleguide.gjs
+++ b/plugins/styleguide/assets/javascripts/discourse/templates/styleguide.gjs
@@ -1,25 +1,7 @@
-import { concat } from "@ember/helper";
-import { i18n } from "discourse-i18n";
-import StyleguideLink from "discourse/plugins/styleguide/discourse/components/styleguide-link";
-import ToggleColorMode from "discourse/plugins/styleguide/discourse/components/toggle-color-mode";
-
export default <template>
+ {{! The section navigation is a sidebar panel that takes over the main sidebar for the length
+ of this route. See the styleguide-sidebar service. }}
<section class="styleguide">
- <section class="styleguide-menu">
- <ToggleColorMode />
-
- {{#each @controller.categories as |c|}}
- <ul>
- <li class="styleguide-heading">
- {{i18n (concat "styleguide.categories." c.id)}}
- </li>
- {{#each c.sections as |s|}}
- <li><StyleguideLink @section={{s}} /></li>
- {{/each}}
- </ul>
- {{/each}}
- </section>
-
<section class="styleguide-contents">
{{outlet}}
</section>
diff --git a/plugins/styleguide/assets/stylesheets/styleguide.scss b/plugins/styleguide/assets/stylesheets/styleguide.scss
index 460afd5dea9..7f86f13f9bd 100644
--- a/plugins/styleguide/assets/stylesheets/styleguide.scss
+++ b/plugins/styleguide/assets/stylesheets/styleguide.scss
@@ -3,9 +3,10 @@
.styleguide {
position: relative;
- display: flex;
- padding: 1rem;
- padding-left: 0;
+
+ // No top padding: the page header's breadcrumb brings its own top margin, and that alone lines
+ // it up with the sidebar's "back to forum" row. Adding padding here pushes it out of that band.
+ padding: 0 1rem 1rem;
.styleguide-note {
padding: 1em;
@@ -13,55 +14,22 @@
margin-bottom: 1em;
}
- .styleguide-menu {
- position: sticky;
- top: calc(var(--header-offset) + 3rem);
- max-height: calc(100vh - 3rem - var(--header-offset));
- flex: 1 0 0;
- overflow-y: auto;
- margin-right: 2rem;
+ // The color mode control shares the breadcrumb's row. The spacing moves from the list to this
+ // container so both items centre against each other: a flex parent no longer collapses the
+ // list's margin, which is what keeps the row level with the sidebar's "back to forum".
+ .d-page-header__breadcrumbs {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 1em;
+ margin: var(--space-2) 0 var(--space-4);
- ul {
- list-style: none;
+ .d-breadcrumbs {
margin: 0;
- margin-bottom: 2em;
-
- &:last-child {
- margin-bottom: 0;
- }
-
- li.styleguide-heading {
- color: var(--primary-medium);
- text-transform: uppercase;
- font-size: 14px;
- }
-
- li {
- margin-bottom: 0.25em;
-
- a {
- color: var(--primary);
- font-size: 14px;
- }
-
- a.active {
- font-weight: bold;
- }
- }
}
}
- .styleguide-contents {
- flex: 4 0 0;
- }
-
.styleguide-section {
- .section-title {
- font-size: var(--font-up-5);
- font-weight: normal;
- margin-bottom: 0.5em;
- }
-
.section-description {
margin-bottom: 2em;
}
diff --git a/plugins/styleguide/config/locales/client.en.yml b/plugins/styleguide/config/locales/client.en.yml
index fd6bd9affe0..c687ca456f6 100644
--- a/plugins/styleguide/config/locales/client.en.yml
+++ b/plugins/styleguide/config/locales/client.en.yml
@@ -7,7 +7,7 @@ en:
js:
styleguide:
title: "Styleguide"
- welcome: "To get started, choose a section from the menu on the left."
+ welcome: "To get started, choose a section from the navigation menu."
categories:
syntax: Syntax
diff --git a/plugins/styleguide/spec/system/page_objects/pages/styleguide.rb b/plugins/styleguide/spec/system/page_objects/pages/styleguide.rb
new file mode 100644
index 00000000000..3376e69ca79
--- /dev/null
+++ b/plugins/styleguide/spec/system/page_objects/pages/styleguide.rb
@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PageObjects
+ module Pages
+ class Styleguide < PageObjects::Pages::Base
+ def visit_index
+ visit("/styleguide")
+ self
+ end
+
+ # Not `has_title?`: Capybara already defines a `have_title` matcher for the document title,
+ # and it would win over this one.
+ def has_heading?(text)
+ has_css?(".styleguide-contents .d-page-header__title", text: text)
+ end
+
+ def has_no_heading?(text)
+ has_no_css?(".styleguide-contents .d-page-header__title", text: text)
+ end
+
+ def has_breadcrumb?(text)
+ has_css?(".styleguide-contents .d-breadcrumbs__item", text: text)
+ end
+
+ # Scoped to the panel because these links get LinkTo's own `active` class rather than the
+ # `--active` modifier the shared sidebar page object looks for.
+ def has_active_nav_link?(text)
+ has_css?(".sidebar-sections.styleguide-panel .sidebar-section-link.active", text: text)
+ end
+
+ COLOR_MODE_MENU = "styleguide-color-mode"
+
+ def select_color_mode(mode)
+ menu = PageObjects::Components::DMenu.new(".toggle-color-mode", COLOR_MODE_MENU)
+ menu.expand
+ menu.option(".toggle-color-mode__#{mode}-option").click
+
+ # The menu content is portalled, and clicking an option tears it down. Waiting for that
+ # to finish keeps a follow-up selection from clicking into a detached element.
+ page.has_no_css?("#d-menu-portals [data-identifier='#{COLOR_MODE_MENU}']")
+ end
+
+ def has_color_mode?(mode)
+ has_css?(".toggle-color-mode[data-current-mode='#{mode}']")
+ end
+
+ def has_no_color_selector?
+ has_no_css?(".toggle-color-mode")
+ end
+ end
+ end
+end
diff --git a/plugins/styleguide/spec/system/smoke_test_spec.rb b/plugins/styleguide/spec/system/smoke_test_spec.rb
index 15b59c7f1e0..2ec5accf0d2 100644
--- a/plugins/styleguide/spec/system/smoke_test_spec.rb
+++ b/plugins/styleguide/spec/system/smoke_test_spec.rb
@@ -3,10 +3,12 @@
RSpec.describe "Styleguide Smoke Test" do
fab!(:admin)
+ let(:styleguide) { PageObjects::Pages::Styleguide.new }
+
# keep this hash updated when adding, removing or renaming components
sections = {
- "SYNTAX" => [{ href: "/syntax/bem", title: "BEM" }],
- "ATOMS" => [
+ "syntax" => [{ href: "/syntax/bem", title: "BEM" }],
+ "atoms" => [
{ href: "/atoms/typography", title: "Typography" },
{ href: "/atoms/font-scale", title: "Font System" },
{ href: "/atoms/buttons", title: "Buttons" },
@@ -20,7 +22,7 @@ RSpec.describe "Styleguide Smoke Test" do
{ href: "/atoms/topic-link", title: "Topic Link and Status" },
{ href: "/atoms/segmented-control", title: "Segmented Control (Button toggle group)" },
],
- "MOLECULES" => [
+ "molecules" => [
{ href: "/molecules/bread-crumbs", title: "Bread Crumbs" },
{ href: "/molecules/categories", title: "Categories" },
{ href: "/molecules/char-counter", title: "Character Counter" },
@@ -38,7 +40,7 @@ RSpec.describe "Styleguide Smoke Test" do
{ href: "/molecules/topic-notifications", title: "Topic Notifications" },
{ href: "/molecules/topic-timer-info", title: "Topic Timers" },
],
- "ORGANISMS" => [
+ "organisms" => [
{ href: "/organisms/post", title: "Post" },
{ href: "/organisms/post-list", title: "Post List" },
{ href: "/organisms/post-oneboxes", title: "Post Oneboxes" },
@@ -65,19 +67,28 @@ RSpec.describe "Styleguide Smoke Test" do
# declared in the sections hash above
it "renders the index page correctly and collect information about the available page" do
visit "/styleguide"
- expect(page).to have_css(".styleguide-contents h1.section-title", text: "Styleguide")
+ expect(styleguide).to have_heading("Styleguide")
existing_sections = {}
page
- .all(".styleguide-menu > ul")
+ .all(".sidebar-sections.styleguide-panel .sidebar-section[data-section-name]")
.each do |section_node|
- section = section_node.find(".styleguide-heading").text.strip
+ # Keyed on the section name rather than the header's text: the name is the contract the
+ # panel actually declares, where the text depends on translation and on casing applied
+ # by the stylesheet.
+ section = section_node["data-section-name"].delete_prefix("styleguide-category-")
existing_sections[section] ||= []
items = existing_sections[section]
- anchors = section_node.all("li a")
- anchors.each { |anchor| items << { title: anchor.text.strip, href: anchor[:href] } }
+ section_node
+ .all(".sidebar-section-link")
+ .each do |link|
+ items << {
+ title: link.find(".sidebar-section-link-content-text").text.strip,
+ href: link[:href],
+ }
+ end
end
expect(existing_sections.keys).to match_array(sections.keys)
@@ -97,11 +108,27 @@ RSpec.describe "Styleguide Smoke Test" do
end
end
+ it "shows the not found page for a section that does not exist" do
+ visit "/styleguide/molecules/does-not-exist"
+
+ expect(page).to have_css(".page-not-found")
+ expect(styleguide).to have_no_heading("Styleguide")
+ end
+
+ it "shows the reader the trail back to the styleguide index" do
+ visit "/styleguide/atoms/buttons"
+
+ expect(styleguide).to have_breadcrumb("Styleguide")
+ expect(styleguide).to have_breadcrumb("Buttons")
+ end
+
it "renders the index page correctly on a site with no default color schemes" do
SiteSetting.default_theme_id = Fabricate(:theme).id
visit "/styleguide"
- expect(page).to have_css(".styleguide-contents h1.section-title", text: "Styleguide")
+ expect(styleguide).to have_heading("Styleguide")
+ # There is nothing to switch to, so the selector hides itself rather than offering a no-op.
+ expect(styleguide).to have_no_color_selector
end
# uses the sections hash to generate a test for each page and check if it renders correctly
@@ -116,7 +143,7 @@ RSpec.describe "Styleguide Smoke Test" do
it "renders the #{section}: #{item[:title]} page correctly" do
visit "/styleguide/#{item[:href]}"
- expect(page).to have_css(".styleguide-contents h1.section-title", text: item[:title])
+ expect(styleguide).to have_heading(item[:title])
end
end
end
@@ -130,7 +157,7 @@ RSpec.describe "Styleguide Smoke Test" do
it "renders a page using HighlightedCode for anonymous users" do
visit "/styleguide/atoms/font-scale"
- expect(page).to have_css(".styleguide-contents h1.section-title", text: "Font System")
+ expect(styleguide).to have_heading("Font System")
expect(page).to have_css("code.hljs")
end
end
@@ -149,7 +176,7 @@ RSpec.describe "Styleguide Smoke Test" do
moderator = Fabricate(:moderator)
sign_in(moderator)
visit "/styleguide"
- expect(page).to have_css(".styleguide-contents h1.section-title", text: "Styleguide")
+ expect(styleguide).to have_heading("Styleguide")
end
end
end
diff --git a/plugins/styleguide/spec/system/styleguide_sidebar_spec.rb b/plugins/styleguide/spec/system/styleguide_sidebar_spec.rb
new file mode 100644
index 00000000000..0a42f376d8d
--- /dev/null
+++ b/plugins/styleguide/spec/system/styleguide_sidebar_spec.rb
@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.describe "Styleguide sidebar panel" do
+ include ThemeScreenshotMarker
+
+ fab!(:admin)
+
+ let(:styleguide) { PageObjects::Pages::Styleguide.new }
+ let(:sidebar) { PageObjects::Components::NavigationMenu::Sidebar.new }
+ let(:sidebar_dropdown) { PageObjects::Components::SidebarHeaderDropdown.new }
+ let(:filter) { PageObjects::Components::Filter.new }
+
+ before do
+ SiteSetting.styleguide_enabled = true
+ SiteSetting.navigation_menu = "sidebar"
+ sign_in(admin)
+ end
+
+ it "replaces the forum sidebar with the styleguide's own navigation" do
+ visit "/styleguide/atoms/buttons"
+
+ expect(sidebar).to be_visible
+ expect(page).to have_css(".sidebar-sections.styleguide-panel")
+
+ %w[syntax atoms molecules organisms].each do |category|
+ expect(sidebar).to have_section("styleguide-category-#{category}")
+ end
+
+ # The forum's own sections are displaced rather than merely pushed down.
+ expect(sidebar).to have_no_section("categories")
+
+ screenshot_marker(label: "styleguide-sidebar", only: :desktop)
+ end
+
+ it "links to a section without leaking a group query param" do
+ visit "/styleguide"
+
+ expect(sidebar).to have_section_link("Buttons", href: "/styleguide/atoms/buttons")
+ end
+
+ it "marks the current section's link as active" do
+ visit "/styleguide/atoms/buttons"
+
+ expect(styleguide).to have_active_nav_link("Buttons")
+ end
+
+ it "hands the sidebar back when leaving the styleguide" do
+ visit "/styleguide/atoms/buttons"
+ expect(sidebar).to have_no_section("categories")
+
+ sidebar.click_back_to_forum
+
+ expect(sidebar).to have_section("categories")
+ expect(page).to have_no_css(".sidebar-sections.styleguide-panel")
+ end
+
+ it "does not offer a switch button for the panel" do
+ visit "/styleguide"
+
+ expect(sidebar).to have_no_switch_button("styleguide")
+ end
+
+ # The styleguide's nav used to render unconditionally, so a reader who prefers the header
+ # dropdown must not lose it now that it lives in the sidebar.
+ it "renders for a reader whose navigation menu preference is the header dropdown" do
+ SiteSetting.navigation_menu = NavigationMenuSiteSetting::HEADER_DROPDOWN
+
+ visit "/styleguide/atoms/buttons"
+
+ expect(page).to have_css(".sidebar-sections.styleguide-panel")
+ end
+
+ # Mobile never renders the fixed sidebar, so the panel reaches the reader through the header
+ # dropdown instead. That is a separate path from the desktop one and needs its own coverage.
+ it "reaches the styleguide navigation through the header dropdown on mobile", mobile: true do
+ visit "/styleguide"
+
+ sidebar_dropdown.click
+
+ expect(page).to have_css(".sidebar-sections.styleguide-panel")
+ expect(sidebar).to have_section("styleguide-category-atoms")
+ expect(sidebar).to have_no_section("categories")
+
+ sidebar.click_link_in_section("styleguide-category-atoms", "styleguide-section-buttons")
+
+ expect(page).to have_current_path("/styleguide/atoms/buttons")
+ expect(sidebar_dropdown).to be_hidden
+ end
+
+ it "filters the sections" do
+ visit "/styleguide"
+
+ filter.filter("typography")
+
+ expect(sidebar).to have_section_link("Typography")
+ expect(sidebar).to have_no_section_link("Buttons")
+ end
+end
diff --git a/plugins/styleguide/spec/system/toggle_color_mode_spec.rb b/plugins/styleguide/spec/system/toggle_color_mode_spec.rb
new file mode 100644
index 00000000000..ad080fbaa04
--- /dev/null
+++ b/plugins/styleguide/spec/system/toggle_color_mode_spec.rb
@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+RSpec.describe "Styleguide color mode selector" do
+ fab!(:admin)
+
+ let!(:dark_scheme) { ColorScheme.find_by(base_scheme_id: ColorScheme::NAMES_TO_ID_MAP["Dark"]) }
+
+ let(:styleguide) { PageObjects::Pages::Styleguide.new }
+ let(:sidebar) { PageObjects::Components::NavigationMenu::Sidebar.new }
+ let(:color_mode) { PageObjects::Components::InterfaceColorMode.new }
+
+ before do
+ SiteSetting.styleguide_enabled = true
+ SiteSetting.navigation_menu = "sidebar"
+ Theme.find_default.update!(dark_color_scheme_id: dark_scheme.id)
+ sign_in(admin)
+ end
+
+ # The selector is torn down and rebuilt on every styleguide navigation, so it has to read the
+ # mode that is actually applied rather than the one it last set.
+ it "keeps showing the applied color mode after the reader opens a section" do
+ styleguide.visit_index
+
+ styleguide.select_color_mode("dark")
+ expect(color_mode).to have_dark_mode_forced
+
+ sidebar.click_link_in_section("styleguide-category-atoms", "styleguide-section-buttons")
+
+ expect(styleguide).to have_color_mode("dark")
+
+ styleguide.select_color_mode("light")
+ expect(color_mode).to have_light_mode_forced
+ end
+
+ it "lets the reader go back to following the system preference" do
+ styleguide.visit_index
+
+ styleguide.select_color_mode("dark")
+ expect(color_mode).to have_dark_mode_forced
+
+ styleguide.select_color_mode("auto")
+
+ expect(color_mode).to have_auto_color_mode
+ expect(styleguide).to have_color_mode("auto")
+ end
+end