@patternfly/patternfly-doc-core 1.5.0 → 1.7.0

package/src/components/ExampleToolbar.tsx

@@ -0,0 +1,296 @@
+// TODO remove this component it is not good and I don't like that I have to add it
+
+import React from 'react'
+import { Button, Form, Tooltip } from '@patternfly/react-core'
+import {
+  CodeEditor,
+  CodeEditorControl,
+  Language,
+} from '@patternfly/react-code-editor'
+import { convertToJSX } from '@patternfly/ast-helpers'
+import ExternalLinkAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-alt-icon'
+import CodepenIcon from '@patternfly/react-icons/dist/esm/icons/codepen-icon'
+import CopyIcon from '@patternfly/react-icons/dist/esm/icons/copy-icon'
+import CodeIcon from '@patternfly/react-icons/dist/esm/icons/code-icon'
+import AngleDoubleRightIcon from '@patternfly/react-icons/dist/esm/icons/angle-double-right-icon'
+import ReplyAllIcon from '@patternfly/react-icons/dist/esm/icons/reply-all-icon'
+
+const copy = (textToCopy: string) => {
+  navigator.clipboard.writeText(textToCopy)
+}
+
+interface TrackEventValue {
+  event_category: string
+  event_label: string
+  value?: number
+}
+
+interface WindowWithGtag extends Window {
+  gtag?: (type: string, name: string, value: TrackEventValue) => void
+}
+const _window = window as WindowWithGtag
+/**
+ * Sends network call using Google Analytic's gtag function
+ * https://developers.google.com/analytics/devguides/collection/gtagjs/events#send_events
+ *
+ * @param name {string} - The value that will appear as the event action in Google Analytics Event reports.
+ * @param eventCategory {string} - The category of the event.
+ * @param eventLabel {string} - The label of the event.
+ * @param [value] {number} - An optional non-negative integer that will appear as the event value.
+ */
+const trackEvent = (
+  name: string,
+  eventCategory: string,
+  eventLabel: string,
+  value?: number,
+) => {
+  value ||= 0
+  if (_window?.gtag) {
+    _window?.gtag('event', name, {
+      // eslint-disable-next-line camelcase
+      event_category: eventCategory,
+      // eslint-disable-next-line camelcase
+      event_label: eventLabel,
+      // Optional non-negative integer
+      ...(value >= 0 && { value }),
+    })
+  }
+}
+
+function getLanguage(lang: string) {
+  if (lang === 'js') {
+    return Language.javascript
+  } else if (lang === 'ts') {
+    return Language.typescript
+  }
+
+  return lang as Language
+}
+
+interface ExampleToolbarProps {
+  fullscreenLink?: string
+  codeBoxParams?: any
+  lang: string
+  isFullscreen?: boolean
+  originalCode: string
+  code: string
+  setCode: (code: string) => void
+  exampleTitle?: string
+}
+
+export const ExampleToolbar = ({
+  // Link to fullscreen example page (each example has one)
+  fullscreenLink,
+  // Params to pass to codesandbox
+  codeBoxParams,
+  // Language of code
+  lang,
+  // Whether the example is fullscreen only
+  isFullscreen,
+  // Original version of the code
+  originalCode,
+  // Current code in editor
+  code,
+  // Callback to set code in parent component
+  setCode,
+  // Title of example used in creating unique labels
+  exampleTitle,
+}: ExampleToolbarProps) => {
+  const [isEditorOpen, setIsEditorOpen] = React.useState(false)
+  const [isCopied, setCopied] = React.useState(false)
+
+  const copyLabel = 'Copy code to clipboard'
+  const languageLabel = `Toggle ${lang.toUpperCase()} code`
+  const codesandboxLabel = 'Open example in CodeSandbox'
+  const fullscreenLabel = 'Open example in new window'
+  const convertLabel = 'Convert example from Typescript to JavaScript'
+  const undoAllLabel = 'Undo all changes'
+
+  const copyAriaLabel = `Copy ${exampleTitle} example code to clipboard`
+  const languageAriaLabel = `Toggle ${lang.toUpperCase()} code in ${exampleTitle} example`
+  const codesandboxAriaLabel = `Open ${exampleTitle} example in CodeSandbox`
+  const fullscreenAriaLabel = `Open ${exampleTitle} example in new window`
+  const convertAriaLabel = `Convert ${exampleTitle} example from Typescript to JavaScript`
+  const undoAllAriaLabel = `Undo all changes to ${exampleTitle}`
+
+  const editorControlProps = {
+    className: 'ws-code-editor-control',
+  }
+
+  const commonTooltipProps = {
+    exitDelay: 300,
+    maxWidth: 'var(--ws-code-editor--tooltip--MaxWidth)',
+  }
+
+  const copyCode = () => {
+    copy(code)
+    setCopied(true)
+  }
+
+  const customControls = (
+    <React.Fragment>
+      <CodeEditorControl
+        icon={
+          <React.Fragment>
+            <CodeIcon />
+            {' ' + lang.toUpperCase()}
+          </React.Fragment>
+        }
+        onClick={() => {
+          setIsEditorOpen(!isEditorOpen)
+          // 1 === expand code, 0 === collapse code
+          trackEvent(
+            'code_editor_control_click',
+            'click_event',
+            'TOGGLE_CODE',
+            isEditorOpen ? 0 : 1,
+          )
+        }}
+        tooltipProps={{
+          content: languageLabel,
+          ...commonTooltipProps,
+        }}
+        aria-label={languageAriaLabel}
+        aria-expanded={isEditorOpen}
+        {...editorControlProps}
+      />
+      <Tooltip
+        content={<div>{isCopied ? 'Code copied' : copyLabel}</div>}
+        maxWidth={(editorControlProps as any)?.maxWidth}
+        exitDelay={isCopied ? 300 : 1600}
+        onTooltipHidden={() => setCopied(false)}
+      >
+        <Button
+          onClick={() => {
+            copyCode()
+            trackEvent('code_editor_control_click', 'click_event', 'COPY_CODE')
+          }}
+          variant="plain"
+          aria-label={copyAriaLabel}
+          className={editorControlProps.className}
+        >
+          <CopyIcon />
+        </Button>
+      </Tooltip>
+      {codeBoxParams && (
+        <Form
+          aria-label={`${codesandboxAriaLabel} form`}
+          action="https://codesandbox.io/api/v1/sandboxes/define"
+          method="POST"
+          target="_blank"
+          style={{ display: 'inline-block' }}
+        >
+          <Tooltip
+            content={codesandboxLabel}
+            maxWidth={(editorControlProps as any).maxWidth}
+          >
+            <Button
+              aria-label={codesandboxAriaLabel}
+              variant="plain"
+              type="submit"
+              onClick={() => {
+                trackEvent(
+                  'code_editor_control_click',
+                  'click_event',
+                  'CODESANDBOX_LINK',
+                )
+              }}
+              className={editorControlProps.className}
+            >
+              <CodepenIcon />
+            </Button>
+          </Tooltip>
+          <input type="hidden" name="parameters" value={codeBoxParams} />
+        </Form>
+      )}
+      {fullscreenLink && (
+        <CodeEditorControl
+          component="a"
+          icon={<ExternalLinkAltIcon />}
+          href={fullscreenLink}
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label={fullscreenAriaLabel}
+          tooltipProps={{
+            content: fullscreenLabel,
+            ...commonTooltipProps,
+          }}
+          onClick={() => {
+            trackEvent(
+              'code_editor_control_click',
+              'click_event',
+              'FULLSCREEN_LINK',
+            )
+          }}
+          {...editorControlProps}
+        />
+      )}
+      {isEditorOpen && lang === 'ts' && (
+        <CodeEditorControl
+          icon={
+            <React.Fragment>
+              {'TS '}
+              <AngleDoubleRightIcon />
+              {' JS'}
+            </React.Fragment>
+          }
+          aria-label={convertAriaLabel}
+          tooltipProps={{
+            content: convertLabel,
+            ...commonTooltipProps,
+          }}
+          onClick={() => {
+            setCode(convertToJSX(code).code)
+            trackEvent('code_editor_control_click', 'click_event', 'TS_TO_JS')
+          }}
+          {...editorControlProps}
+        />
+      )}
+      {code !== originalCode && (
+        <CodeEditorControl
+          icon={<ReplyAllIcon />}
+          aria-label={undoAllAriaLabel}
+          tooltipProps={{
+            content: undoAllLabel,
+            ...commonTooltipProps,
+          }}
+          onClick={() => {
+            setCode(originalCode)
+            trackEvent('code_editor_control_click', 'click_event', 'RESET_CODE')
+          }}
+          {...editorControlProps}
+        />
+      )}
+    </React.Fragment>
+  )
+
+  // TODO: check if worth adding react, patternfly, and example types
+  // https://microsoft.github.io/monaco-editor/api/interfaces/monaco.languages.typescript.languageservicedefaults.html#addextralib
+  const onEditorDidMount = (_editor: any, monaco: any) => {
+    monaco.languages.typescript.typescriptDefaults.setCompilerOptions({
+      jsx: true,
+      ...monaco.languages.typescript.typescriptDefaults.getCompilerOptions(),
+    })
+    monaco.languages.typescript.typescriptDefaults.setDiagnosticsOptions({
+      noSemanticValidation: true,
+      noSyntaxValidation: true,
+      noSuggestionDiagnostics: true,
+      onlyVisible: true,
+    })
+  }
+
+  return (
+    <CodeEditor
+      customControls={customControls}
+      showEditor={isEditorOpen}
+      language={getLanguage(lang)}
+      height="400px"
+      code={code}
+      onChange={(newCode) => setCode(newCode)}
+      onEditorDidMount={onEditorDidMount}
+      isReadOnly={isFullscreen}
+      className={`${isEditorOpen ? 'ws-example-code-expanded ' : ''}ws-code-editor`}
+      isHeaderPlain
+    />
+  )
+}

package/src/components/LiveExample.astro

@@ -0,0 +1,7 @@
+---
+import { LiveExample as LiveExampleBase } from './LiveExample'
+
+const { src } = Astro.props
+---
+
+<LiveExampleBase src={src} client:only="react" />

package/src/components/LiveExample.tsx

@@ -0,0 +1,42 @@
+import React, { useState } from 'react'
+import { convertToReactComponent } from '@patternfly/ast-helpers'
+import * as reactCoreModule from '@patternfly/react-core'
+import { ExampleToolbar } from './ExampleToolbar'
+interface LiveExampleProps {
+  src: string
+}
+
+function getLivePreview(editorCode: string) {
+  const scope = { ...reactCoreModule, ...{ useState } }
+  const { code: transformedCode } = convertToReactComponent(editorCode)
+
+  const componentNames = Object.keys(scope)
+  const componentValues = Object.values(scope)
+
+  const getPreviewComponent = new Function(
+    'React',
+    ...componentNames,
+    transformedCode,
+  )
+  const PreviewComponent = getPreviewComponent(React, ...componentValues)
+
+  return <PreviewComponent />
+}
+
+export const LiveExample = ({ src }: LiveExampleProps) => {
+  const [code, setCode] = useState(src)
+  const livePreview = getLivePreview(code)
+
+  return (
+    <>
+      {livePreview}
+      <ExampleToolbar
+        originalCode={src}
+        code={code}
+        setCode={setCode}
+        lang="ts"
+        isFullscreen={false}
+      />
+    </>
+  )
+}

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,14 @@ 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]),
+      cssPrefix: z
+        .union([
+          z.string().transform((val) => [val]),
+          z.array(z.string()),
+          z.null().transform(() => undefined),
+        ])
+        .optional(),
     }),
   })
 }

package/src/content.ts

@@ -1,5 +1,6 @@
 export const content = [
-  { base: 'textContent', pattern: '*.md', name: "textContent" } 
+  { base: 'textContent', pattern: '*.{md,mdx}', name: 'textContent' },
+  { base: 'textContent', pattern: 'examples/*/*.mdx', name: 'examples' },
   // TODO: Remove. Uncomment for local testing.
   // {
   //   "packageName":"@patternfly/react-core",

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,12 @@
 ---
 import { getCollection, render } from 'astro:content'
-import { Title } from '@patternfly/react-core'
+import { Title, 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'
 
 export async function getStaticPaths() {
   const collections = await Promise.all(
@@ -20,16 +21,18 @@ 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
-  return Astro.rewrite(`/components/${kebabCase(id)}/${componentTabs[id][0]}`);
+if (section === 'components') {
+  // if section is components, rewrite to first tab content
+  return Astro.rewrite(`/components/${kebabCase(id)}/${componentTabs[id][0]}`)
 }
 ---
 
@@ -37,10 +40,17 @@ 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 />
+  <Stack hasGutter>
+    <StackItem>
+      <PropsTables propComponents={propComponents} server:defer />
+    </StackItem>
+    <StackItem>
+      <CSSTable cssPrefix={cssPrefix} server:defer />
+    </StackItem>
+  </Stack>
 </MainLayout>

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

@@ -1,74 +1,141 @@
 ---
 import { getCollection, render } from 'astro:content'
-import { Title, PageSection, Content as PFContent } from '@patternfly/react-core'
+import { Title, PageSection, Stack, StackItem } from '@patternfly/react-core'
 import MainLayout from '../../../layouts/Main.astro'
-import { content } from "../../../content"
+import { content } from '../../../content'
 import { kebabCase } from 'change-case'
-import { componentTabs, tabNames, buildTab, sortTabs } from '../../../globals';
+import { componentTabs, tabNames, buildTab, sortTabs } from '../../../globals'
 import PropsTables from '../../../components/PropsTables.astro'
+import {
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  p,
+  a,
+  small,
+  blockquote,
+  pre,
+  hr,
+  ul,
+  ol,
+  dl,
+  li,
+  dt,
+  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(content.map(async (entry) => await getCollection(entry.name as 'textContent')))
+  const collections = await Promise.all(
+    content.map(
+      async (entry) => await getCollection(entry.name as 'textContent'),
+    ),
+  )
 
-  const flatCol =  collections.flat().map((entry) => {
+  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`;
+    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`;
+        tab = `${tab}-deprecated`
       }
     }
-    buildTab(entry, tab);
+    buildTab(entry, tab)
 
     return {
-      params: { page: kebabCase(entry.data.id), section: entry.data.section, tab },
+      params: {
+        page: kebabCase(entry.data.id),
+        section: entry.data.section,
+        tab,
+      },
       props: { entry, ...entry.data },
     }
   })
 
-  sortTabs() 
-  return flatCol;
+  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;
-
+const currentPath = Astro.url.pathname
 ---
 
 <MainLayout>
   {
     title && (
       <Title headingLevel="h1" size="4xl">
-        {title} 
+        {title}
       </Title>
     )
   }
-  {componentTabs[id] && (
-    <PageSection id="ws-sticky-nav-tabs" stickyOnBreakpoint={{ default: 'top' }} type="tabs">
-      <div class="pf-v6-c-tabs pf-m-page-insets pf-m-no-border-bottom">
-        <ul class="pf-v6-c-tabs__list">
-          {componentTabs[id].map((tab: string) => (
-            // eslint-disable-next-line react/jsx-key
-            <li
-              class={`pf-v6-c-tabs__item${currentPath === `/${section}/${kebabCase(id)}/${tab}` ? ' pf-m-current' : ''}`}
-            >
-              <a class="pf-v6-c-tabs__link" href={`/${section}/${kebabCase(id)}/${tab}`}>
-                {tabNames[tab]}
-              </a>
-            </li>
-          ))}
-        </ul>
-      </div>
-    </PageSection>
-  )}
+  {
+    componentTabs[id] && (
+      <PageSection
+        id="ws-sticky-nav-tabs"
+        stickyOnBreakpoint={{ default: 'top' }}
+        type="tabs"
+      >
+        <div class="pf-v6-c-tabs pf-m-page-insets pf-m-no-border-bottom">
+          <ul class="pf-v6-c-tabs__list">
+            {componentTabs[id].map((tab: string) => (
+              // eslint-disable-next-line react/jsx-key
+              <li
+                class={`pf-v6-c-tabs__item${currentPath === `/${section}/${kebabCase(id)}/${tab}` ? ' pf-m-current' : ''}`}
+              >
+                <a
+                  class="pf-v6-c-tabs__link"
+                  href={`/${section}/${kebabCase(id)}/${tab}`}
+                >
+                  {tabNames[tab]}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      </PageSection>
+    )
+  }
   <PageSection id="main-content" isFilled>
-    <PFContent>
-      <Content />
-      <PropsTables propComponents={propComponents} server:defer />
-    </PFContent>
+    <Content
+      components={{
+        h1,
+        h2,
+        h3,
+        h4,
+        h5,
+        h6,
+        p,
+        a,
+        small,
+        blockquote,
+        pre,
+        hr,
+        ul,
+        ol,
+        dl,
+        li,
+        dt,
+        dd,
+        LiveExample,
+      }}
+    />
+    <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'
 ---