@patternfly/patternfly-doc-core 1.6.0 → 1.8.0

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

@@ -17,8 +17,8 @@ function defineContent(contentObj: CollectionDefinition) {
   // TODO: Expand for other packages that remain under the react umbrella (Table, CodeEditor, etc)
   const tabMap: any = {
     'react-component-docs': 'react',
-    'core-component-docs': 'html' 
-  };
+    'core-component-docs': 'html',
+  }
 
   return defineCollection({
     loader: glob({ base: dir, pattern }),
@@ -28,7 +28,15 @@ 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]),
+          z.array(z.string()),
+          z.null().transform(() => undefined),
+        ])
+        .optional(),
     }),
   })
 }

package/src/layouts/Main.astro

@@ -1,11 +1,11 @@
 ---
 import '@patternfly/patternfly/patternfly.css'
+import '../styles/global.scss'
 import { ClientRouter } from 'astro:transitions'
 
 import Page from '../components/Page.astro'
 import Masthead from '../components/Masthead.astro'
 import Navigation from '../components/Navigation.astro'
-
 ---
 
 <html lang="en" transition:animate="none">
@@ -27,11 +27,15 @@ import Navigation from '../components/Navigation.astro'
 </html>
 
 <script>
-  const themePreference = window.localStorage.getItem ('theme-preference');
-  document?.querySelector('html')?.classList.toggle('pf-v6-theme-dark', themePreference === 'dark' ); 
-  
-  document.addEventListener("astro:after-swap", () => {
-      const themePreference = window.localStorage.getItem ('theme-preference');
-      document?.querySelector('html')?.classList.toggle('pf-v6-theme-dark', themePreference === 'dark' ); 
-  });
+  const themePreference = window.localStorage.getItem('theme-preference')
+  document
+    ?.querySelector('html')
+    ?.classList.toggle('pf-v6-theme-dark', themePreference === 'dark')
+
+  document.addEventListener('astro:after-swap', () => {
+    const themePreference = window.localStorage.getItem('theme-preference')
+    document
+      ?.querySelector('html')
+      ?.classList.toggle('pf-v6-theme-dark', themePreference === 'dark')
+  })
 </script>

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

@@ -1,11 +1,13 @@
 ---
 import { getCollection, render } from 'astro:content'
-import { Title } 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(
@@ -20,15 +22,16 @@ export async function getStaticPaths() {
       entry,
       title: entry.data.title,
       propComponents: entry.data.propComponents,
+      cssPrefix: entry.data.cssPrefix,
     },
   }))
 }
 
-const { entry, propComponents } = Astro.props
+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
+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]}`);
 }
 ---
@@ -37,10 +40,21 @@ if(section === 'components') { // if section is components, rewrite to first tab
   {
     title && (
       <Title headingLevel="h1" size="4xl">
-        {title} 
+        {title}
       </Title>
     )
   }
-  <Content />
-  <PropsTables propComponents={propComponents} server:defer />
+    <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

@@ -1,6 +1,6 @@
 ---
 import { getCollection, render } from 'astro:content'
-import { Title, PageSection } 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'
@@ -27,6 +27,7 @@ import {
   dd,
 } from '../../../components/Content'
 import LiveExample from '../../../components/LiveExample.astro'
+import CSSTable from '../../../components/CSSTable.astro'
 
 export async function getStaticPaths() {
   const collections = await Promise.all(
@@ -35,34 +36,32 @@ 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
 }
 
-const { entry, propComponents } = Astro.props
+const { entry, propComponents, cssPrefix } = Astro.props
+
 const { title, id, section } = entry.data
 const { Content } = await render(entry)
 const currentPath = Astro.url.pathname
@@ -127,6 +126,13 @@ const currentPath = Astro.url.pathname
         LiveExample,
       }}
     />
-    <PropsTables propComponents={propComponents} server:defer />
+    <Stack hasGutter>
+      <StackItem>
+        <PropsTables propComponents={propComponents} server:defer />
+      </StackItem>
+      <StackItem>
+        <CSSTable cssPrefix={cssPrefix} server:defer />
+      </StackItem>
+    </Stack>
   </PageSection>
 </MainLayout>

package/src/pages/index.astro

@@ -1,5 +1,4 @@
 ---
-import '../styles/global.scss'
 import MainLayout from '../layouts/Main.astro'
 ---
 

package/src/styles/global.scss

@@ -1 +1,47 @@
-// custom global scss would go here
+.circle {
+  height: 1em;
+  display: inline-block;
+  aspect-ratio: 1 / 1;
+  border-radius: 50%;
+  border: var(--pf-t--global--border--width--regular) solid
+    var(--pf-t--global--background--color--inverse--default);
+  box-shadow: var(--pf-t--global--box-shadow--sm);
+}
+
+.rotate-90-deg {
+  transform: rotate(90deg);
+}
+
+.ws-heading {
+  position: relative;
+}
+
+.ws-heading-anchor {
+  color: var(--pf-t--global--icon--color--regular);
+  transform: translate(calc(-100% - var(--pf-t--global--spacer--xs)), -50%);
+  opacity: 0;
+  position: absolute;
+  left: 0;
+  top: 50%;
+  --pf-v6-c-content--a--Color: var(--pf-t--global--icon--color--regular);
+  --pf-v6-c-button--m-plain--PaddingInlineEnd: 0;
+  --pf-v6-c-button--m-plain--PaddingInlineStart: 0;
+  --pf-v6-c-button--MinWidth: unset;
+}
+
+.ws-heading-anchor.pf-v6-c-button:hover,
+.ws-heading-anchor.pf-v6-c-button:focus {
+  --pf-v6-c-button--hover--Color: var(--pf-t--global--icon--color--regular);
+  --pf-v6-c-button--BackgroundColor: transparent;
+  --pf-v6-c-content--a--hover--Color: var(--pf-t--global--icon--color--regular);
+}
+
+.ws-heading-anchor-icon {
+  height: 0.75rem;
+  width: 0.75rem;
+}
+
+.ws-heading:hover .ws-heading-anchor,
+.ws-heading-anchor:focus {
+  opacity: 1;
+}

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from './capitalize'
+export * from './slugger'