@patternfly/patternfly-doc-core 1.7.0 → 1.8.1

package/src/components/section-gallery/SectionGallery.tsx

@@ -0,0 +1,111 @@
+import { useState } from 'react'
+
+import { SectionGalleryToolbar } from './SectionGalleryToolbar'
+import { SectionGalleryGridLayout } from './SectionGalleryGridLayout'
+import { SectionGalleryListLayout } from './SectionGalleryListLayout'
+import { snakeCase } from 'change-case'
+
+import './SectionGallery.css'
+
+export interface SectionGalleryItem {
+  /** Name of the gallery item. Should match the page name of the item for routing, or an item should provide a link property in the SectionGalleryItemData. */
+  name: string
+  /** Image file import */
+  img: any
+  /** Data of the gallery item */
+  data: SectionGalleryItemData
+}
+
+export interface SectionGalleryItemData {
+  /** Path to the item illustration */ // TODO: remove if img method is fine
+  illustration: string
+  /** Summary text of the item */
+  summary: string
+  /** Label included in the item footer. Choose from a preset or pass a custom label. */
+  label?: 'beta' | 'demo' | 'deprecated'
+  /** Link to the item, relative to the section, e.g. "/{section}/{page}" */
+  link?: string
+}
+
+interface SectionGalleryProps {
+  /** Collection of illustations for the gallery */
+  illustrations?: any
+  /** Section where the gallery is located */
+  section: string
+  /** Data of all gallery items */
+  galleryItemsData: Record<string, SectionGalleryItemData>
+  /** Placeholder text for the gallery search input */
+  placeholderText?: string
+  /** Text for the amount of gallery items */
+  countText?: string
+  /** Starting layout for the gallery */
+  initialLayout?: 'grid' | 'list'
+  /** Indicates the grid layout has item summary text */
+  hasGridText?: boolean
+  /** Indicates the grid layout has item images */
+  hasGridImages?: boolean
+  /** Indicates the list layout has item summary text */
+  hasListText?: boolean
+  /** Indicates the list layout has item images */
+  hasListImages?: boolean
+}
+
+export const SectionGallery = ({
+  illustrations,
+  section,
+  galleryItemsData,
+  placeholderText,
+  countText,
+  initialLayout = 'grid',
+  hasGridText = false,
+  hasGridImages = false,
+  hasListText = false,
+  hasListImages = false,
+}: SectionGalleryProps) => {
+  const [searchTerm, setSearchTerm] = useState('')
+  const [layoutView, setLayoutView] = useState(initialLayout)
+
+  const galleryItems: SectionGalleryItem[] = Object.entries(galleryItemsData)
+    .map(([galleryItem, galleryItemData]) => ({
+      name: galleryItem,
+      img: illustrations ? illustrations[snakeCase(galleryItem)] : undefined,
+      data: galleryItemData,
+    }))
+    .sort((item1, item2) => item1.name.localeCompare(item2.name))
+
+  const nonCharsRegex = /[^A-Z0-9]+/gi
+  const filteringTerm = searchTerm.replace(nonCharsRegex, '')
+  const filteredItems: SectionGalleryItem[] = galleryItems.filter((item) =>
+    new RegExp(filteringTerm).test(item.name.replace(nonCharsRegex, '')),
+  )
+
+  return (
+    <div className="ws-section-gallery">
+      <SectionGalleryToolbar
+        galleryItemCount={galleryItems.length}
+        searchTerm={searchTerm}
+        setSearchTerm={setSearchTerm}
+        layoutView={layoutView}
+        setLayoutView={setLayoutView}
+        placeholderText={placeholderText}
+        countText={countText}
+      />
+      {layoutView === 'grid' && (
+        <SectionGalleryGridLayout
+          section={section}
+          galleryItems={filteredItems}
+          hasGridText={hasGridText}
+          hasGridImages={hasGridImages}
+        />
+      )}
+      {layoutView === 'list' && (
+        <SectionGalleryListLayout
+          section={section}
+          galleryItems={filteredItems}
+          hasListText={hasListText}
+          hasListImages={hasListImages}
+        />
+      )}
+    </div>
+  )
+}

package/src/components/section-gallery/SectionGalleryGridLayout.tsx

@@ -0,0 +1,97 @@
+import React from 'react'
+import {
+  Gallery,
+  GalleryItem,
+  Card,
+  CardHeader,
+  CardTitle,
+  CardBody,
+  CardFooter,
+  Label,
+  Content,
+} from '@patternfly/react-core'
+import { SectionGalleryItem } from './SectionGallery'
+import { sentenceCase } from 'change-case'
+import { convertToReactComponent } from '@patternfly/ast-helpers'
+
+interface SectionGalleryGridLayoutProps {
+  /** Section where the gallery is located */
+  section: string
+  /** List of gallery items */
+  galleryItems: SectionGalleryItem[]
+  /** Indicates the grid layout has item summary text */
+  hasGridText: boolean
+  /** Indicates the grid layout has item images */
+  hasGridImages: boolean
+}
+
+export const SectionGalleryGridLayout = ({
+  section,
+  galleryItems,
+  hasGridText,
+  hasGridImages,
+}: SectionGalleryGridLayoutProps) => (
+  <Gallery hasGutter>
+    {galleryItems.map(({ name, img, data }, idx) => {
+      const itemLink = data.link || `/${section}/${name}`
+
+      //TODO: rethink how JSX / enriched content is passed to framework
+      const summaryNoLinks = data.summary.replace(
+        /<a[^>]*>([^<]+)<\/a>/gm,
+        '$1',
+      )
+      const { code } = convertToReactComponent(`<>${summaryNoLinks}</>`)
+      const getSummaryComponent = new Function('React', code)
+
+      return (
+        <GalleryItem span={4} key={idx}>
+          <Card id={name} key={idx} isClickable>
+            <CardHeader
+              selectableActions={{
+                to: itemLink,
+                selectableActionId: `${name}-input`,
+                selectableActionAriaLabelledby: name,
+                name: `clickable-card-${idx}`,
+              }}
+            >
+              <CardTitle>{sentenceCase(name)}</CardTitle>
+            </CardHeader>
+            {(hasGridImages || hasGridText) && (
+              <CardBody>
+                {hasGridImages && img && (
+                  <img src={img.src} alt={`${name} illustration`} /> // verify whether this img.src approach is correct
+                )}
+                {hasGridText && (
+                  <Content isEditorial>
+                    <Content component="p">
+                      {getSummaryComponent(React)}
+                    </Content>
+                  </Content>
+                )}
+              </CardBody>
+            )}
+            {data.label && (
+              <CardFooter>
+                {data.label === 'beta' && (
+                  <Label color="blue" isCompact>
+                    Beta
+                  </Label>
+                )}
+                {data.label === 'deprecated' && (
+                  <Label color="grey" isCompact>
+                    Deprecated
+                  </Label>
+                )}
+                {data.label === 'demo' && (
+                  <Label color="purple" isCompact>
+                    Demo
+                  </Label>
+                )}
+              </CardFooter>
+            )}
+          </Card>
+        </GalleryItem>
+      )
+    })}
+  </Gallery>
+)

package/src/components/section-gallery/SectionGalleryListLayout.tsx

@@ -0,0 +1,108 @@
+import React from 'react'
+import {
+  DataList,
+  DataListItem,
+  DataListItemRow,
+  DataListItemCells,
+  DataListCell,
+  Split,
+  SplitItem,
+  Label,
+  Content,
+  ContentVariants,
+} from '@patternfly/react-core'
+import { SectionGalleryItem } from './SectionGallery'
+import { sentenceCase } from 'change-case'
+import { convertToReactComponent } from '@patternfly/ast-helpers'
+
+interface SectionGalleryListLayoutProps {
+  /** Section where the gallery is located */
+  section: string
+  /** List of gallery items */
+  galleryItems: SectionGalleryItem[]
+  /** Indicates the list layout has item summary text */
+  hasListText: boolean
+  /** Indicates the list layout has item images */
+  hasListImages: boolean
+}
+
+export const SectionGalleryListLayout = ({
+  section,
+  galleryItems,
+  hasListText,
+  hasListImages,
+}: SectionGalleryListLayoutProps) => (
+  <DataList onSelectDataListItem={() => {}} aria-label="gallery-list">
+    {galleryItems.map(({ name, img, data }, idx) => {
+      const itemLink = data.link || `/${section}/${name}`
+
+      //TODO: rethink how JSX / enriched content is passed to framework
+      const summaryNoLinks = data.summary.replace(
+        /<a[^>]*>([^<]+)<\/a>/gm,
+        '$1',
+      )
+      const { code } = convertToReactComponent(`<>${summaryNoLinks}</>`)
+      const getSummaryComponent = new Function('React', code)
+
+      return (
+        <a href={itemLink} key={idx} className="ws-section-gallery-item">
+          <DataListItem>
+            <DataListItemRow>
+              <DataListItemCells
+                dataListCells={[
+                  hasListImages && img && (
+                    <DataListCell width={1} key="illustration">
+                      <div>
+                        <img
+                          src={img.src} // same as GridLayout, check whether this is the best method
+                          alt={`${name} illustration`}
+                        />
+                      </div>
+                    </DataListCell>
+                  ),
+                  <DataListCell width={5} key="text-description">
+                    <Split
+                      className={hasListText ? 'pf-v6-u-mb-md' : undefined}
+                    >
+                      <SplitItem isFilled>
+                        <Content isEditorial>
+                          <Content component={ContentVariants.h2}>
+                            <span>{sentenceCase(name)}</span>
+                          </Content>
+                        </Content>
+                      </SplitItem>
+                      <SplitItem>
+                        {data.label === 'beta' && (
+                          <Label color="blue" isCompact>
+                            Beta
+                          </Label>
+                        )}
+                        {data.label === 'deprecated' && (
+                          <Label color="grey" isCompact>
+                            Deprecated
+                          </Label>
+                        )}
+                        {data.label === 'demo' && (
+                          <Label color="purple" isCompact>
+                            Demo
+                          </Label>
+                        )}
+                      </SplitItem>
+                    </Split>
+                    {hasListText && (
+                      <Content isEditorial>
+                        <Content component="p">
+                          {getSummaryComponent(React)}
+                        </Content>
+                      </Content>
+                    )}
+                  </DataListCell>,
+                ]}
+              />
+            </DataListItemRow>
+          </DataListItem>
+        </a>
+      )
+    })}
+  </DataList>
+)

package/src/components/section-gallery/SectionGalleryToolbar.tsx

@@ -0,0 +1,93 @@
+import { CSSProperties, Dispatch, SetStateAction } from 'react'
+import {
+  Button,
+  SearchInput,
+  Toolbar,
+  ToolbarContent,
+  ToolbarItem,
+  Content,
+  ContentVariants,
+  ToggleGroup,
+  ToggleGroupItem,
+} from '@patternfly/react-core'
+import ListIcon from '@patternfly/react-icons/dist/esm/icons/list-icon'
+import ThIcon from '@patternfly/react-icons/dist/esm/icons/th-icon'
+
+interface SectionGalleryToolbarProps {
+  /** Total count of gallery items */
+  galleryItemCount: number
+  /** Current search term */
+  searchTerm: string
+  /** Setter for search term */
+  setSearchTerm: Dispatch<SetStateAction<string>>
+  /** Current layout */
+  layoutView: 'grid' | 'list'
+  /** Setter for layout */
+  setLayoutView: Dispatch<SetStateAction<'grid' | 'list'>>
+  /** Placeholder text for the gallery search input */
+  placeholderText?: string
+  /** Text for the amount of gallery items */
+  countText?: string
+}
+
+export const SectionGalleryToolbar = ({
+  galleryItemCount,
+  searchTerm,
+  setSearchTerm,
+  layoutView,
+  setLayoutView,
+  placeholderText = 'Search by name',
+  countText = ' items',
+}: SectionGalleryToolbarProps) => (
+  <Toolbar isSticky>
+    <ToolbarContent>
+      <ToolbarItem>
+        <SearchInput
+          value={searchTerm}
+          placeholder={placeholderText}
+          onChange={(_evt, val) => {
+            setSearchTerm(val)
+          }}
+        />
+      </ToolbarItem>
+      {searchTerm && (
+        <ToolbarItem>
+          <Button variant="link" onClick={() => setSearchTerm('')}>
+            Reset
+          </Button>
+        </ToolbarItem>
+      )}
+      <ToolbarItem>
+        <ToggleGroup>
+          <ToggleGroupItem
+            icon={<ThIcon />}
+            aria-label="grid icon button"
+            isSelected={layoutView === 'grid'}
+            onChange={() => setLayoutView('grid')}
+          ></ToggleGroupItem>
+          <ToggleGroupItem
+            icon={<ListIcon />}
+            aria-label="list icon button"
+            isSelected={layoutView === 'list'}
+            onChange={() => setLayoutView('list')}
+          ></ToggleGroupItem>
+        </ToggleGroup>
+      </ToolbarItem>
+      <ToolbarItem
+        variant="pagination"
+        gap={{ default: 'gapMd', md: 'gapNone' }}
+        style={
+          {
+            '--pf-v6-c-toolbar__item--MinWidth': 'max-content',
+          } as CSSProperties
+        }
+        className="pf-m-align-self-center"
+      >
+        <Content isEditorial component={ContentVariants.small}>
+          {galleryItemCount}
+          {countText}
+        </Content>
+      </ToolbarItem>
+    </ToolbarContent>
+  </Toolbar>
+)

package/src/content.config.ts

@@ -28,7 +28,8 @@ function defineContent(contentObj: CollectionDefinition) {
       subsection: z.string().optional(),
       title: z.string().optional(),
       propComponents: z.array(z.string()).optional(),
-      tab: z.string().optional().default(tabMap[name]),
+      tab: z.string().optional().default(tabMap[name]), // for component tabs
+      sortValue: z.number().optional(), // used for sorting nav entries,
       cssPrefix: z
         .union([
           z.string().transform((val) => [val]),

package/src/layouts/Main.astro

@@ -38,4 +38,32 @@ import Navigation from '../components/Navigation.astro'
       ?.querySelector('html')
       ?.classList.toggle('pf-v6-theme-dark', themePreference === 'dark')
   })
+
+  const scrollToHash = (hash: string) => {
+    const targetElement = document.querySelector(hash)
+    if (targetElement) {
+      targetElement.scrollIntoView({ behavior: 'smooth' })
+    }
+  }
+
+  document.addEventListener('DOMContentLoaded', () => {
+    if (window.location.hash) {
+      const hash = window.location.hash
+
+      // Without this, page would focus on anchor link without scrolling to it
+      history.replaceState(null, '', ' ')
+
+      setTimeout(() => {
+        scrollToHash(hash)
+        history.replaceState(null, '', hash)
+      }, 500)
+    }
+  })
+
+  // Handle changes that happen after the initial page load
+  window.addEventListener('hashchange', () => {
+    if (window.location.hash) {
+      scrollToHash(window.location.hash)
+    }
+  })
 </script>

package/src/pages/[section]/[...page].astro

@@ -1,12 +1,13 @@
 ---
 import { getCollection, render } from 'astro:content'
-import { Title, Stack, StackItem } from '@patternfly/react-core'
+import { Title, PageSection, Stack, StackItem } from '@patternfly/react-core'
 import MainLayout from '../../layouts/Main.astro'
 import { content } from '../../content'
 import { kebabCase } from 'change-case'
 import { componentTabs } from '../../globals'
 import PropsTables from '../../components/PropsTables.astro'
 import CSSTable from '../../components/CSSTable.astro'
+import SectionGallery from '../../components/section-gallery/SectionGallery.astro'
 
 export async function getStaticPaths() {
   const collections = await Promise.all(
@@ -30,9 +31,8 @@ const { entry, propComponents, cssPrefix } = Astro.props
 const { title, id, section } = entry.data
 const { Content } = await render(entry)
 
-if (section === 'components') {
-  // if section is components, rewrite to first tab content
-  return Astro.rewrite(`/components/${kebabCase(id)}/${componentTabs[id][0]}`)
+if(section === 'components' && componentTabs[id]) { // if section is components & tab exists, rewrite to first tab content
+  return Astro.rewrite(`/components/${kebabCase(id)}/${componentTabs[id][0]}`);
 }
 ---
 
@@ -44,13 +44,17 @@ if (section === 'components') {
       </Title>
     )
   }
-  <Content />
-  <Stack hasGutter>
-    <StackItem>
-      <PropsTables propComponents={propComponents} server:defer />
-    </StackItem>
-    <StackItem>
-      <CSSTable cssPrefix={cssPrefix} server:defer />
-    </StackItem>
-  </Stack>
+    <PageSection id="main-content" isFilled>
+        <Content components={{
+          SectionGallery
+        }}/>
+        <Stack hasGutter>
+          <StackItem>
+            <PropsTables propComponents={propComponents} server:defer />
+          </StackItem>
+          <StackItem>
+            <CSSTable cssPrefix={cssPrefix} server:defer />
+          </StackItem>
+        </Stack>
+  </PageSection>
 </MainLayout>

package/src/pages/[section]/[page]/[...tab].astro

@@ -36,28 +36,25 @@ export async function getStaticPaths() {
     ),
   )
 
-  const flatCol = collections.flat().map((entry) => {
-    // Build tabs dictionary
-    let tab = entry.data.tab
-    if (tab) {
-      // check for demos/deprecated
-      if (entry.id.includes('demos')) {
-        tab = `${tab}-demos`
-      } else if (entry.id.includes('deprecated')) {
-        tab = `${tab}-deprecated`
+  const flatCol =  collections.flat()
+    .filter((entry) => entry.data.tab) // only pages with a tab should match this route
+    .map((entry) => {
+      // Build tabs dictionary
+      let tab = entry.data.tab;
+      if(tab) { // check for demos/deprecated
+        if(entry.id.includes('demos')) {
+          tab = `${tab}-demos`;
+        } else if (entry.id.includes('deprecated')) {
+          tab = `${tab}-deprecated`;
+        }
       }
-    }
-    buildTab(entry, tab)
+      buildTab(entry, tab);
 
-    return {
-      params: {
-        page: kebabCase(entry.data.id),
-        section: entry.data.section,
-        tab,
-      },
-      props: { entry, ...entry.data },
-    }
-  })
+      return {
+        params: { page: kebabCase(entry.data.id), section: entry.data.section, tab },
+        props: { entry, ...entry.data },
+      }
+    })
 
   sortTabs()
   return flatCol

package/src/styles/global.scss

@@ -14,6 +14,7 @@
 
 .ws-heading {
   position: relative;
+  scroll-margin-top: 3rem;
 }
 
 .ws-heading-anchor {

package/textContent/AllComponents.mdx

@@ -0,0 +1,16 @@
+---
+id: All components
+title: All components
+section: components
+sortValue: 1
+---
+
+import { componentsData } from './components-data.js'
+
+<SectionGallery
+  section="components"
+  galleryItemsData={componentsData}
+  placeholderText="Search components by name"
+  hasGridText
+  hasListText
+/>