Add searchable glossary (#12608)

Add a searchable glossary at `/resources/glossary` with two initial terms that we can add to over time.

For now, don't add the new page to the sidenav until we add a few more important terms.

Author: parlough

firebase.json

@@ -58,6 +58,8 @@
       { "source": "/flutter-for-:platform*", "destination": "/get-started/flutter-for/:platform*-devs", "type": 301 },
       { "source": "/formatting", "destination": "/tools/formatting", "type": 301 },
       { "source": "/gestures", "destination": "/ui/advanced/gestures", "type": 301 },
+      { "source": "/glossary", "destination": "/resources/glossary", "type": 301 },
+      { "source": "/glossary/:entry", "destination": "/resources/glossary#:entry", "type": 301 },
       { "source": "/hot-reload", "destination": "/tools/hot-reload", "type": 301 },
       { "source": "/ide-setup", "destination": "/tools/editors", "type": 301 },
       { "source": "/images/catalog-widget-placeholder.png", "destination": "/assets/images/docs/catalog-widget-placeholder.png", "type": 301 },

site/lib/_sass/_site.scss

@@ -22,6 +22,7 @@
 @use 'components/cookie-notice';
 @use 'components/dropdown';
 @use 'components/expansion-list';
+@use 'components/filter-search';
 @use 'components/footer';
 @use 'components/header';
 @use 'components/icons';
@@ -38,6 +39,7 @@
 @use 'components/trailing';
 
 // Styles for specific pages, alphabetically ordered.
+@use 'pages/glossary';
 @use 'pages/learning-resources-index';
 @use 'pages/not-found';
 @use 'pages/search';

site/lib/_sass/components/_button.scss

@@ -35,7 +35,7 @@ button {
     font-weight: 500;
     font-family: var(--site-ui-fontFamily);
     gap: 0.3rem;
-    padding: 0.5rem 1rem;
+    padding: 0.4rem 0.9rem;
     text-decoration: none;
     cursor: pointer;
   }
@@ -46,6 +46,11 @@ button {
     outline-offset: 2px;
     user-select: none;
 
+    span.material-symbols {
+      font-variation-settings: 'FILL' 1;
+      font-size: 20px;
+    }
+
     &:hover {
       @include mixins.interaction-style(8%);
     }

site/lib/_sass/components/_card.scss

@@ -1,5 +1,13 @@
 @use '../base/mixins';
 
+.card-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--card-grid-gap, 1rem);
+  margin: 0;
+  justify-content: center;
+}
+
 .card-grid {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--card-min-width, 15rem)), 1fr));
@@ -30,7 +38,9 @@
     --card-min-width: 10rem;
     grid-auto-rows: 1fr;
   }
+}
 
+.card-grid, .card-list {
   .card {
     display: flex;
     flex-direction: column;
@@ -101,7 +111,7 @@
       }
     }
 
-    .card-content {
+    &:not(.glossary-card) .card-content {
       display: flex;
       align-items: center;
       gap: 0.75rem;
@@ -225,7 +235,6 @@
   }
 }
 
-
 .card-image-holder-material-3 {
   position: relative;
   align-items: center;

site/lib/_sass/components/_content.scss

@@ -1,4 +1,4 @@
-#page-content {
+main {
   display: flex;
   flex-direction: column;
   justify-content: center;

site/lib/_sass/components/_filter-search.scss

@@ -0,0 +1,62 @@
+#filter-and-search {
+  display: flex;
+  flex-direction: column;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+  margin-block-start: 1rem;
+  margin-block-end: 1rem;
+
+  &.hidden {
+    display: none;
+  }
+
+  .search-row {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    width: 100%;
+    gap: 0.5rem;
+
+    .search-wrapper {
+      display: flex;
+      align-items: center;
+      width: 100%;
+
+      border: 1px solid var(--site-outline);
+      border-radius: 1rem;
+      height: 3rem;
+      padding: 0 .5rem;
+
+      &:has(:focus-visible) {
+        outline: 2px solid var(--site-primary-color);
+        border-color: transparent;
+      }
+
+      .leading-icon {
+        padding-left: 0.25rem;
+        user-select: none;
+      }
+
+      input {
+        background: none;
+        width: 100%;
+        font-size: 1rem;
+        cursor: text;
+
+        &:focus {
+          outline: none;
+        }
+
+        &::-webkit-search-cancel-button {
+          display: none;
+        }
+      }
+    }
+  }
+
+  + section.content-search-results {
+    margin-block-start: 0.5rem;
+    margin-block-end: 1rem;
+  }
+}

site/lib/_sass/pages/_glossary.scss

@@ -0,0 +1,97 @@
+@use '../base/mixins';
+
+body.glossary-page main {
+  .glossary-card {
+    height: auto;
+    padding: 0.75rem;
+
+    .expandable-content {
+      border-top: 0.05rem solid var(--site-inset-borderColor);
+      padding-top: 0.5rem;
+    }
+
+    &.collapsed {
+      min-height: 8rem;
+
+      .initial-content {
+        // Only show the first paragraph if collapsed.
+        > :not(:first-child) {
+          display: none;
+        }
+      }
+
+      .expandable-content {
+        display: none;
+      }
+
+      .expand-button {
+        transform: rotate(180deg);
+      }
+    }
+
+    .expand-button {
+      &:hover, &:focus-within {
+        transition: transform .25s ease-out;
+      }
+    }
+
+    .card-header {
+      display: flex;
+      flex-direction: row;
+      justify-content: space-between;
+      align-items: center;
+    }
+  }
+
+  .details-header {
+    font-weight: 500;
+    margin-bottom: 0.5rem;
+    margin-top: 0.5rem;
+    font-size: 1rem;
+  }
+
+  .resources-list {
+    list-style: none;
+    padding: 0.5rem;
+    margin: 0;
+
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+
+    li {
+      display: flex;
+
+      .filled-button {
+        text-wrap: pretty;
+        padding: 0.25rem 0.75rem;
+      }
+    }
+  }
+
+  .initial-content, .expandable-content {
+    > :first-child {
+      margin-top: 0;
+    }
+
+    > :last-child {
+      margin-bottom: 0;
+    }
+  }
+
+  .card-header-buttons {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.25rem;
+
+    .icon-button {
+      border-radius: 1.5rem;
+
+      > span {
+        font-size: 1.5rem;
+      }
+    }
+  }
+}

site/lib/jaspr_options.dart

@@ -29,10 +29,12 @@ import 'package:docs_flutter_dev_site/src/components/layout/theme_switcher.dart'
     as prefix10;
 import 'package:docs_flutter_dev_site/src/components/pages/archive_table.dart'
     as prefix11;
-import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters.dart'
+import 'package:docs_flutter_dev_site/src/components/pages/glossary_search_section.dart'
     as prefix12;
-import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters_sidebar.dart'
+import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters.dart'
     as prefix13;
+import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters_sidebar.dart'
+    as prefix14;
 
 /// Default [JasprOptions] for use with your jaspr project.
 ///
@@ -105,13 +107,18 @@ JasprOptions get defaultJasprOptions => JasprOptions(
       params: _prefix11ArchiveTable,
     ),
 
-    prefix12.LearningResourceFilters:
-        ClientTarget<prefix12.LearningResourceFilters>(
+    prefix12.GlossarySearchSection:
+        ClientTarget<prefix12.GlossarySearchSection>(
+          'src/components/pages/glossary_search_section',
+        ),
+
+    prefix13.LearningResourceFilters:
+        ClientTarget<prefix13.LearningResourceFilters>(
           'src/components/pages/learning_resource_filters',
         ),
 
-    prefix13.LearningResourceFiltersSidebar:
-        ClientTarget<prefix13.LearningResourceFiltersSidebar>(
+    prefix14.LearningResourceFiltersSidebar:
+        ClientTarget<prefix14.LearningResourceFiltersSidebar>(
           'src/components/pages/learning_resource_filters_sidebar',
         ),
   },

site/lib/src/client/global_scripts.dart

@@ -41,6 +41,7 @@ void _setUpSite() {
   _setUpSearchKeybindings();
   _setUpTabs();
   _setUpCollapsibleElements();
+  _setUpExpandableCards();
   _setUpPlatformKeys();
   _setUpToc();
 }
@@ -255,6 +256,48 @@ void _setUpCollapsibleElements() {
   }
 }
 
+void _setUpExpandableCards() {
+  var currentFragment = web.window.location.hash.trim().toLowerCase();
+  if (currentFragment.startsWith('#')) {
+    // Remove the leading '#' from the fragment.
+    currentFragment = currentFragment.substring(1);
+  }
+  final expandableCards = web.document.querySelectorAll('.expandable-card');
+  web.Element? targetCard;
+
+  for (var i = 0; i < expandableCards.length; i++) {
+    final card = expandableCards.item(i) as web.Element;
+    final expandButton = card.querySelector('.expand-button');
+    if (expandButton == null) continue;
+
+    expandButton.addEventListener(
+      'click',
+      ((web.Event e) {
+        if (card.classList.contains('collapsed')) {
+          card.classList.remove('collapsed');
+          expandButton.ariaExpanded = 'true';
+        } else {
+          card.classList.add('collapsed');
+          expandButton.ariaExpanded = 'false';
+        }
+        e.preventDefault();
+      }).toJS,
+    );
+
+    if (card.id != currentFragment) {
+      card.classList.add('collapsed');
+      expandButton.ariaExpanded = 'false';
+    } else {
+      targetCard = card;
+    }
+  }
+
+  if (targetCard != null) {
+    // Scroll the expanded card into view.
+    targetCard.scrollIntoView();
+  }
+}
+
 void _setUpPlatformKeys() {
   final os = getOS();
   // Use Command key for macOS, Control key for other OS.