Docs site supports docs for unstable APIs (#2344)

apps/website/astro.config.ts

@@ -15,8 +15,6 @@ import astroExpressiveCode from 'astro-expressive-code';
 import * as lightningCss from 'lightningcss';
 import { itwinuiReactAliases } from 'helpers';
 
-const isDev = process.env.NODE_ENV === 'development';
-
 // https://astro.build/config
 export default defineConfig({
   site: 'https://itwinui.bentley.com',
@@ -26,6 +24,7 @@ export default defineConfig({
         './src/components/PropsTable.astro',
         './src/components/LiveExample.astro',
         './src/components/Placeholder.astro',
+        './src/components/UnstableApiCard.astro',
         { examples: 'AllExamples' },
       ],
     }),

apps/website/src/components/DocsNoteCard.astro

@@ -0,0 +1,27 @@
+<div {...Astro.props}>
+  <slot name='icon' />
+  <slot name='content' />
+</div>
+
+<style lang='scss'>
+  @layer components {
+    div {
+      display: flex;
+      align-items: center;
+      gap: var(--space-3);
+      padding: var(--space-3);
+      border: solid 1px var(--color-highlight-2);
+      border-radius: var(--border-radius-1);
+
+      p {
+        color: var(--color-text);
+      }
+
+      svg {
+        color: var(--color-highlight-2);
+        height: var(--space-8);
+        width: var(--space-8);
+      }
+    }
+  }
+</style>

apps/website/src/components/FeedbackLink.astro

@@ -5,7 +5,7 @@ type Props = { page: string } & astroHTML.JSX.AnchorHTMLAttributes;
 let { page, ...rest } = Astro.props;
 
 const repoUrl = 'https://github.com/iTwin/iTwinUI';
-const githubFeedbackUrl = `${repoUrl}/discussions/new?category=documentation&title=Feedback%20on%20%60${page}%60&body=Replace%20this%20text%20with%20your%20feedback%20on%20the%20%60${page}%60%20page.`;
+const githubFeedbackUrl = `${repoUrl}/discussions/new?category=feedback&title=Feedback%20on%20%60${page}%60&body=Replace%20this%20text%20with%20your%20feedback%20on%20the%20%60${page}%60%20page.`;
 ---
 
 <a href={githubFeedbackUrl} {...rest}>

apps/website/src/components/Placeholder.astro

@@ -1,5 +1,6 @@
 ---
 import InformationIcon from '~/icons/InformationIcon.astro';
+import DocsNoteCard from './DocsNoteCard.astro';
 
 export type Props = {
   /** ending of the url for a specific react-workshop page */
@@ -11,33 +12,10 @@ const { componentPageName, ...rest } = Astro.props;
 const storyUrl = `https://itwin.github.io/iTwinUI/react/?story=${componentPageName}`;
 ---
 
-<div {...rest}>
-  <InformationIcon aria-hidden='true' />
-  <p>
+<DocsNoteCard {...rest}>
+  <InformationIcon aria-hidden='true' slot='icon' />
+  <p slot='content'>
     This page has not yet been finished and is being worked on. In the meantime, you can view the
     <a href={storyUrl}>stories</a>.
   </p>
-</div>
-
-<style lang='scss'>
-  @layer components {
-    div {
-      display: flex;
-      align-items: center;
-      gap: var(--space-3);
-      padding: var(--space-3);
-      border: solid 1px var(--color-highlight-2);
-      border-radius: var(--border-radius-1);
-
-      p {
-        color: var(--color-text);
-      }
-
-      svg {
-        color: var(--color-highlight-2);
-        height: var(--space-8);
-        width: var(--space-8);
-      }
-    }
-  }
-</style>
+</DocsNoteCard>

apps/website/src/components/PropsTable.astro

@@ -14,19 +14,25 @@ import snarkdown from 'snarkdown';
 
 export interface Props {
   path: string;
+  /**
+   * Uses the props for the `componentName`. If not provided, it will use the filename as the `componentName`.
+   */
+  componentName?: string;
 }
 
 const defaultHandlers = Object.values(docgenHandlers).map((handler) => handler);
 const defaultResolver = docgenResolver.findAllExportedComponentDefinitions;
 const defaultImporter = docgenImporters.makeFsImporter();
 
-const relativePath = Astro.props.path.replace(
+const { path: pathProp, componentName } = Astro.props as Props;
+
+const relativePath = pathProp.replace(
   '@itwin/itwinui-react',
-  '../../packages/itwinui-react', // relative from root of `website` workspace
+  '../../packages/itwinui-react' // relative from root of `website` workspace
 );
 
 const componentPath = path.join(__dirname, relativePath);
-const componentName = path.parse(componentPath).name.split('.')[0]; // Spliting on `.` since some files are .d.ts files
+const componentNameFallback = path.parse(componentPath).name.split('.')[0]; // Spliting on `.` since some files are .d.ts files
 const src = fs.readFileSync(componentPath, 'utf8');
 
 const docgenResults = componentPath.endsWith('.tsx')
@@ -35,7 +41,9 @@ const docgenResults = componentPath.endsWith('.tsx')
     }) as DocumentationObject[])
   : docgenTsParse(componentPath);
 
-const componentDoc = [...docgenResults].find((docs) => docs['displayName'] === componentName);
+const componentDoc = [...docgenResults].find(
+  (docs) => docs['displayName'] === (componentName ?? componentNameFallback)
+);
 ---
 
 <div class='wrapper'>

apps/website/src/components/UnstableApiCard.astro

@@ -0,0 +1,15 @@
+---
+import WarningIcon from '~/icons/WarningIcon.astro';
+import DocsNoteCard from './DocsNoteCard.astro';
+
+const feedbackUrl = 'https://github.com/iTwin/iTwinUI/discussions/new?category=feedback';
+---
+
+<DocsNoteCard {...Astro.props}>
+  <WarningIcon aria-hidden='true' slot='icon' />
+  <p slot='content'>
+    <strong>Unstable</strong>: This component is marked unstable to help us gather <a
+      href={feedbackUrl}>feedback</a
+    > and improve it. Thus, there could be future breaking changes to this component.
+  </p>
+</DocsNoteCard>

apps/website/src/icons/WarningIcon.astro

@@ -0,0 +1,6 @@
+<svg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 16 16' {...Astro.props}>
+  <path
+    fill='currentColor'
+    d='M15.868 13.267l-6.77-11.62a1.15 1.15 0 00-1.1-.67 1.17 1.17 0 00-1.1.69l-6.77 11.59a1.2 1.2 0 001.1 1.72h13.45a1.19 1.19 0 001.19-1.71zm-6.87-.29h-2v-2h2zm0-3h-2v-5h2z'
+  ></path>
+</svg>