New HQ Style Guide (for Bootstrap 5 Pages), and Bootstrap 5 Migration Guide

corehq/apps/hqwebapp/context.py

@@ -0,0 +1,35 @@
+from collections import namedtuple
+
+Section = namedtuple('Section', 'page_name url')
+ParentPage = namedtuple('ParentPage', 'title url')
+
+
+def get_page_context(page_title, page_url, page_name=None, parent_pages=None, domain=None, section=None):
+    """This sets up the page context for functional views inheriting from the following base templates:
+    hqwebapp/{bootstrap_version}/base_page.html
+    hqwebapp/{bootstrap_version}/base_section.html
+        note: do not inherit from two_column.html, unless you have a very specific use-case
+        for navigation, see the style guide section on Navigation
+
+    :param page_title: an instance of ``str``, title of the page...inserted into <title></title> tags
+    :param page_url: an instance of ``str``, often reverse("urlname") or reverse("urlname", args=[...])
+    :param page_name: an instance of ``str``, human-visible page name, defaults to page_title
+    :param parent_pages: ``None`` or a ``list`` of ``ParentPage``
+    :param domain: an instance of ``str``, the domain slug
+    :param section: an instance of the ``Section`` context
+    """
+    page_name = page_name or page_title
+    parent_pages = parent_pages or []
+    base_context = {
+        'current_page': {
+            'page_name': page_name,
+            'title': page_title,
+            'url': page_url,
+            'parents': parent_pages,
+        },
+    }
+    if domain:
+        base_context['domain'] = domain
+    if section:
+        base_context['section'] = section
+    return base_context

corehq/apps/hqwebapp/static/hqwebapp/scss/styleguide.scss

@@ -0,0 +1,224 @@
+@import "functions";
+@import "commcarehq/variables";
+@import "variables";
+@import "variables-dark";
+
+// Layout structure inspired by Bootstrap's 5.3 docs page
+
+.sg-gutter {
+  --bs-gutter-x: 3rem;
+}
+
+.sg-layout {
+  display: grid;
+  grid-template-areas: "sidebar main";
+  grid-template-columns: 1fr 5fr;
+  gap: 1.5rem;
+  font-size: 1rem;
+}
+
+.sg-example {
+  font-size: $font-size-base;
+
+  pre {
+    font-size: .8rem;
+  }
+}
+
+.sg-sidebar {
+  grid-area: sidebar;
+
+  @media (min-width: 992px) {
+    position: -webkit-sticky;
+    position: sticky;
+    top: 5rem;
+    display: block !important;
+    height: calc(100vh - 6rem);
+    padding-left: 0.25rem;
+    margin-left: -0.25rem;
+    overflow-y: auto;
+  }
+}
+
+.sg-main {
+  grid-area: main;
+
+  grid-template-areas:
+    "intro toc"
+    "content toc";
+  grid-template-rows: auto 1fr;
+  grid-template-columns: 4fr 1fr;
+
+  @media (min-width: 768px) {
+    display: grid;
+    gap: inherit;
+  }
+}
+
+.sg-title {
+  font-size: 3rem;
+}
+
+.sg-lead {
+  font-size: 1.5rem;
+}
+
+.sg-intro {
+  grid-area: intro;
+}
+
+.sg-toc {
+  grid-area: toc;
+  font-size: 1rem;
+
+  @media (min-width: 992px) {
+    position: -webkit-sticky;
+    position: sticky;
+    top: 5rem;
+    right: 0;
+    z-index: 2;
+    height: calc(100vh - 7rem);
+    overflow-y: auto;
+  }
+
+}
+
+.sg-toc nav {
+  font-size: 0.875rem;
+
+  ul {
+    padding-left: 0;
+    margin-bottom: 0;
+    list-style: none;
+
+    ul {
+      padding-left: 1rem;
+    }
+  }
+
+  a {
+    display: block;
+    padding: 0.125rem 0 0.125rem 0.75rem;
+    text-decoration: none;
+    border-left: 0.125rem solid transparent;
+
+    &.active {
+      font-weight: 500;
+      border-left-color: $color-purple-dark;
+    }
+  }
+
+}
+
+.sg-content {
+  grid-area: content;
+  min-width: 1px;
+}
+.sg-links-link {
+  padding: 3px 10px;
+  display: block;
+
+  &.active {
+    font-weight: 600;
+  }
+
+  &.active,
+  &:hover {
+    background-color: $cc-brand-hi;
+  }
+}
+
+code {
+  color: $purple;
+  background: none;
+  border: none;
+  font-weight: bold;
+}
+
+pre.ace-chrome {
+  background-color: transparent;
+  line-height: 1.25rem;
+}
+
+pre.ace-chrome .ace_marker-layer .ace_bracket {
+  border: none;
+}
+
+pre.ace-chrome .ace_comment {
+  font-weight: bold;
+}
+
+$sg-color-preview: (
+  "blue-100": $blue-100,
+  "blue-200": $blue-200,
+  "blue-300": $blue-300,
+  "blue-400": $blue-400,
+  "blue-500": $blue-500,
+  "blue-600": $blue-600,
+  "blue-700": $blue-700,
+  "blue-800": $blue-800,
+  "blue-900": $blue-900,
+  "gray-100": $gray-100,
+  "gray-200": $gray-200,
+  "gray-300": $gray-300,
+  "gray-400": $gray-400,
+  "gray-500": $gray-500,
+  "gray-600": $gray-600,
+  "gray-700": $gray-700,
+  "gray-800": $gray-800,
+  "gray-900": $gray-900,
+  "indigo-100": $indigo-100,
+  "indigo-200": $indigo-200,
+  "indigo-300": $indigo-300,
+  "indigo-400": $indigo-400,
+  "indigo-500": $indigo-500,
+  "indigo-600": $indigo-600,
+  "indigo-700": $indigo-700,
+  "indigo-800": $indigo-800,
+  "indigo-900": $indigo-900,
+  "purple-100": $purple-100,
+  "purple-200": $purple-200,
+  "purple-300": $purple-300,
+  "purple-400": $purple-400,
+  "purple-500": $purple-500,
+  "purple-600": $purple-600,
+  "purple-700": $purple-700,
+  "purple-800": $purple-800,
+  "purple-900": $purple-900,
+  "pink-100": $pink-100,
+  "pink-200": $pink-200,
+  "pink-300": $pink-300,
+  "pink-400": $pink-400,
+  "pink-500": $pink-500,
+  "pink-600": $pink-600,
+  "pink-700": $pink-700,
+  "pink-800": $pink-800,
+  "pink-900": $pink-900,
+  "salmon-100": $salmon-100,
+  "salmon-200": $salmon-200,
+  "salmon-300": $salmon-300,
+  "salmon-400": $salmon-400,
+  "salmon-500": $salmon-500,
+  "salmon-600": $salmon-600,
+  "salmon-700": $salmon-700,
+  "salmon-800": $salmon-800,
+  "salmon-900": $salmon-900,
+  "indigo": $indigo,
+  "purple": $purple,
+  "pink": $pink,
+  "salmon": $salmon,
+  "orange": $orange,
+  "dimagi-deep-purple": $dimagi-deep-purple,
+  "dimagi-sky": $dimagi-sky,
+  "dimagi-indigo": $dimagi-indigo,
+  "dimagi-marigold": $dimagi-marigold,
+  "dimagi-sunset": $dimagi-sunset,
+  "dimagi-mango": $dimagi-mango,
+);
+
+@each $color, $value in $sg-color-preview {
+  .sg-bg-#{$color} {
+    color: color-contrast($value);
+    background-color: $value;
+  }
+}