feat: New storybook documentation structure #419

tibuurcio · 2024-09-18T19:19:27Z

Summary

This PR introduces the new folder structure for controlling Storybook documentation. It's mainly structure so contents are still marked as TBD but are planned to be worked on next. It does that by doing a few things:

Introduces PR previews for Storybook using pr-preview-action
- For this to happen, we had to also change the action we used for publishing Storybook from main. We are now using github-pages-deploy-action
Introduces the ability for Storybook to read .md and .mdx files from the docs/ folder and uses the file structure for controlling the left nav menu.
Ability to write .mdx files in GitHub Flavored Markdown format by using the remark-gfm package.
Ability to have mermaid flowcharts rendered by storybook by using the mdx-mermaid package.
Changes the default folder in current component stories from Aquarium to Components to better match the new structure.

Reference Issue (For mParticle employees only. Ignore if you are an outside contributor)

Closes https://go.mparticle.com/work/UNI-981
Closes https://go.mparticle.com/work/UNI-979

ilyusha · 2024-09-18T19:19:31Z

Review Forge

Click Here for AI Insights

github-actions · 2024-09-18T19:49:02Z

PR Preview Action v1.4.8
Preview removed because the pull request was closed.
2024-09-26 14:29 UTC

…lays it correctly

gabyzif · 2024-09-19T13:24:08Z

This looks amazing :)

Can you add TBD in the following pages

And can you add a note with an overview of what's the plan for the docs are? :)

tibuurcio · 2024-09-20T14:50:03Z

This looks amazing :)

Can you add TBD in the following pages

Components

Components

Candidates

[Candidates] (https://mparticle.github.io/aquarium/pr-preview/pr-419/?path=/docs/component-process-candidate-components-promoting-to-a-component--documentation)

Foundation

Candidates

Directory

And can you add a note with an overview of what's the plan for the docs are? :)

Done!

Didn't know where to put the note so I just put the following in the initial page:

This is where all component related documentation will live at mParticle. This is mainly a work in progress at this point
and we are actively working on it.

tibuurcio · 2024-09-20T21:00:53Z

.github/workflows/publish-storybook.yml

This looks terrible in unified view. Please use split for a better experience reviewing.

tibuurcio · 2024-09-20T21:11:07Z

.github/workflows/publish-storybook-pr-preview.yml

+        run: |
+          npm install
+          npm run build-storybook
+          touch ./storybook-static/.nojekyll


This is needed otherwise Github Pages fails to pick up some of the bundled JS files generated by Storybook's build process.

https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages

tibuurcio · 2024-09-20T21:12:48Z

docs/Candidate Components/Directory/Date Range Filter/SelectWithRangePicker.tsx

Copied this from Nancy to use as an example. Not all candidate components need story examples like this. We could simply link to git corp where it's used and to the figma file. Did it in this case too see how it would work.

tibuurcio · 2024-09-20T21:13:21Z

docs/Component Process/Candidate Components/Using existing ones.mdx

Example rendering a mermaid chart

…rticle/aquarium into feat/new-storybook-structure

tibuurcio · 2024-09-25T20:45:28Z

docs/Candidate Components/Directory/Date Range Filter/Documentation.mdx

+<ul>
+  <li>
+    <div style={{ display: 'flex', alignItems: 'center' }}>
+      <img src="https://badgen.net/badge/icon/Figma?icon=libraries&label&color=purple" alt="Repo" style={{ marginRight: 8 }}/>
+      <a href="https://www.figma.com/design/hDSxMHoLlMlLeYbgvT3A6d/Observability-Exploration?node-id=2733-147740&node-type=canvas&t=WfJOqsHGC3JStCh3-0" target="_top" rel="nofollow" className="sbdocs sbdocs-a">Specs</a>
+    </div>
+  </li>
+  <li>
+    <div style={{ display: 'flex', alignItems: 'center' }}>
+      <img src="https://badgen.net/badge/icon/GitHub?icon=github&label" alt="Repo" style={{ marginRight: 8 }}/>
+      <a href="https://git.corp.mparticle.com/mParticle/mPServer/blob/main/src/UI/MP.UI.Web.Nancy/Assets/private/aurelia/src/viewmodels/observability/trace/components/SelectWithRangePicker/SelectWithRangePicker.tsx" target="_top" rel="nofollow" className="sbdocs sbdocs-a">mPServer Example</a>
+    </div>
+  </li>
+</ul>


To be improved, we can create a reusable component for this.

tibuurcio · 2024-09-25T20:46:24Z

docs/Candidate Components/Directory/Date Range Filter/SelectWithRangePicker.tsx

+
+interface SelectWithRangePickerProps<ValueType, OptionType>
+  extends Omit<
+    // @ts-expect-error only used in stories as an example


Copied this from the CDP example where it's using it (observability).

So we do not need candidate components code when we are documenting them in the Aquarium but this was easy enough to add that I gave it a shot. The idea is sharing the link where this is used in the platforms and not this code. It's here only for interactivity with the component directly in the Story.

gabyzif

lgtm!

# [1.33.0-fix-nested-css-error.1](v1.32.0...v1.33.0-fix-nested-css-error.1) (2024-09-30) ### Bug Fixes * add a background color to test css ([9ef257e](9ef257e)) ### Features * New storybook documentation structure ([#419](#419)) ([1a870bc](1a870bc))

mparticle-automation · 2024-09-30T11:38:07Z

🎉 This PR is included in version 1.33.0-fix-nested-css-error.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

# [1.33.0-ant-update.1](v1.32.0...v1.33.0-ant-update.1) (2024-09-30) ### Bug Fixes * fix qualifier alignment ([4ff5f32](4ff5f32)) * fix ts erros ([90864de](90864de)) * merge main ([30dbb30](30dbb30)) * remove @esbuild/darwin-arm64@0.23.1 ([54c96e6](54c96e6)) * solve merge conflicts, types cleanup ([0978c40](0978c40)) * update button interface ([442e0ec](442e0ec)) * update cascader dropdown postion ([d855a09](d855a09)) * update dropdown ([660663b](660663b)) * update qualifier position ([65cd477](65cd477)) ### Features * antd upgrade ([e3bb862](e3bb862)) * New storybook documentation structure ([#419](#419)) ([1a870bc](1a870bc)) * upgrade style ([8d61675](8d61675))

mparticle-automation · 2024-09-30T14:02:12Z

🎉 This PR is included in version 1.33.0-ant-update.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

# [1.33.0](v1.32.0...v1.33.0) (2024-09-30) ### Features * ant upgrade to 5.20 ([#421](#421)) ([49b4bf8](49b4bf8)) * New storybook documentation structure ([#419](#419)) ([1a870bc](1a870bc))

mparticle-automation · 2024-09-30T16:08:03Z

🎉 This PR is included in version 1.33.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

# 1.0.0-fix-semantic-release.1 (2024-10-28) ### Bug Fixes * Design tokens update + icons alignment fix ([#460](#460)) ([9c93165](9c93165)) * a useEffect Hook has been added to detect if the value received … ([#339](#339)) ([0e1ab5d](0e1ab5d)) * active workspace style ([#148](#148)) ([a276806](a276806)) * add current color fill to icon ([#374](#374)) ([12c698c](12c698c)) * add horizontal gap in suite selector ([#391](#391)) ([74a43d0](74a43d0)) * add icons ([#399](#399)) ([3343c26](3343c26)) * add icons for overview map ([#275](#275)) ([a4bb97d](a4bb97d)) * Add Icons in Aquarium ([#395](#395)) ([d554ed5](d554ed5)) * add info icon ([#381](#381)) ([d3aa957](d3aa957)) * add more icon ([#403](#403)) ([3abc3b7](3abc3b7)) * add new icons ([#380](#380)) ([db88c4e](db88c4e)) * add width auto to be able to manage the wdith from the component ([#368](#368)) ([b47c45f](b47c45f)) * button-alligned center ([#287](#287)) ([d8c056d](d8c056d)) * **cascader:** makes cascader use the aquarium configprovider and theme ([21800e2](21800e2)) * correct QueryItem Cascader and Action cosmetic bugs/flaws ([f5e6032](f5e6032)) * correct usage of Typography in Watermark.stories.tsx ([f8b32cb](f8b32cb)) * ensure PostCSS handles CSS unnesting in Vite config ([#457](#457)) ([1978e65](1978e65)) * export notification center props ([#418](#418)) ([2ea78c2](2ea78c2)) * exported types ([#448](#448)) ([a978175](a978175)) * fix broken stories due to typography update ([d64be86](d64be86)) * fix issue on prettifier ([#446](#446)) ([03668b6](03668b6)) * fix QueryItem.ValueSelector.Cascader's selectedDisplayValue type ([e74053d](e74053d)) * fixes path to be / on UPS cookie creation options ([#240](#240)) ([0cebf44](0cebf44)) * hide expand icon in global navigation lists ([#178](#178)) ([edd21db](edd21db)) * hide minimap after user clicks on a button ([#264](#264)) ([21a399c](21a399c)) * icon color not changing on button hover ([#363](#363)) ([aa07067](aa07067)) * Icon component build issue ([d7e2faf](d7e2faf)) * improve workspace selector performace ([#370](#370)) ([590e231](590e231)) * Input now support refs ([#169](#169)) ([20a7e47](20a7e47)) * **input:** wraps Input.Search in Aquarium ConfigProvider ([0fbba18](0fbba18)) * lazy load ValueSelector to fix Storybook test runner ([#298](#298)) ([4cd501b](4cd501b)) * **lint:** fix linting problems ([c343136](c343136)) * make onChange prop of QueryItem InputText optional ([7a1532f](7a1532f)) * make QueryItem Cascader options reactive ([50f11bc](50f11bc)) * make the workspace-selector label smaller ([#359](#359)) ([05c4338](05c4338)) * minor compatibility changes to QueryItem Qualifier and Cascader ([5065bdd](5065bdd)) * minor tweaks to TextInput to make it fully compatible ([be5deab](be5deab)) * nav link target ([#166](#166)) ([092a3aa](092a3aa)) * **NavigationSearch:** swaps Ctrl for Cmd on Macs ([a0b7d63](a0b7d63)) * notification center export z-index ([#422](#422)) ([ce01227](ce01227)) * PR review suggestions ([f1ed504](f1ed504)) * **queryitem:** change Input.Search to Input in Cascader's popover to prevent preact type error ([80b1469](80b1469)) * remove -t patch from sem release ([fa41baa](fa41baa)) * remove \dist files accidentally committed ([ef5a16b](ef5a16b)) * remove circle-dashed.svg, it's a duplicate ([aac4829](aac4829)) * remove hover effect on active state ([#278](#278)) ([9f89fa1](9f89fa1)) * remove LESS syntax from query-item.css ([643402c](643402c)) * rename icons ([#364](#364)) ([223c47d](223c47d)) * Revert design tokens update ([#361](#361)) ([cd9dbc9](cd9dbc9)) * rollback variables/style ([#310](#310)) ([efcaf5c](efcaf5c)) * signout onclick being triggered on render when there are no orgs ([#337](#337)) ([77f2b1a](77f2b1a)) * style build missing custom rules ([#147](#147)) ([3a66b26](3a66b26)) * sub menu links should open the correct herf ([#167](#167)) ([6b52fea](6b52fea)) * **typography:** fix exporting/structure of Typography and its subtypes ([cd097f8](cd097f8)) * unnest css ([#390](#390)) ([03d3ccb](03d3ccb)) * unnesting minimap styles ([#253](#253)) ([067f24d](067f24d)) * update design tokens ([#375](#375)) ([e818591](e818591)) * update empty component ([#371](#371)) ([655e252](655e252)) * update icons that did not obey the color prop ([#445](#445)) ([68006e3](68006e3)) * update more typography stories ([cd3344c](cd3344c)) * update nav link active background color ([#376](#376)) ([3965e60](3965e60)) * update release.config.cjs ([859b3bb](859b3bb)) * update release.config.cjs tag format version ([93ee2ec](93ee2ec)) * update release.yml to test semantic release ([5dcf0a7](5dcf0a7)) * use semantic release token ([7af705c](7af705c)) * use unique tags ([61d7886](61d7886)) * workspace selector positioning ([#338](#338)) ([9561a49](9561a49)) * **workspaceselector:** fix key duplication in the WorkspaceSelector ([2967c68](2967c68)) * **workspaceselector:** fix performance problems by swapping Antd Menu component with native ul ([8a0257b](8a0257b)) * yet more typography corrections ([81fce66](81fce66)) ### Features * add Action QueryItem ([f76ea2b](f76ea2b)) * add datepicker example ([#408](#408)) ([0b4b46b](0b4b46b)) * Add directory icon ([#319](#319)) ([a2b4132](a2b4132)) * add Help Icon ([6bae0ed](6bae0ed)) * Add links to the minimap ([#246](#246)) ([80bd00c](80bd00c)) * add loadData functionality to QueryItem Cascader ([ced4994](ced4994)) * add lock/unlock icons; rename previous lock to paywall ([#340](#340)) ([eaf6998](eaf6998)) * add mp colors to storybook and remove token to css from pre com… ([#405](#405)) ([40dffbf](40dffbf)) * add notification center ([#416](#416)) ([4c44206](4c44206)) * Add notification icon ([#345](#345)) ([2c9d13e](2c9d13e)) * add overview dt icon ([#362](#362)) ([78d7854](78d7854)) * add placeholder to QueryItem's TextInput ([30bde49](30bde49)) * add premiumDt icon ([#346](#346)) ([b3e2817](b3e2817)) * add prettifier ([#404](#404)) ([a99793f](a99793f)) * add QueryItem-related icons ([89fb3b8](89fb3b8)) * add QueryItem.Text component ([8f0b7bd](8f0b7bd)) * Add size prop to `Typography.Text` component ([#262](#262)) ([0c14f00](0c14f00)) * add value props to Qualifier and Cascader ([16042d7](16042d7)) * add variants to icons ([#355](#355)) ([1112674](1112674)) * add workspace label to Workspace Selector ([#323](#323)) ([bdb3c70](bdb3c70)) * Adds stylelint with recommended configs and rules from Indicative ([#82](#82)) ([4dd5380](4dd5380)) * Adds SuitesReminder hook to get a consistent look across platforms for the reminder notification ([#221](#221)) ([533428e](533428e)) * Allow importing types ([#65](#65)) ([7fe8981](7fe8981)) * Allow override theme for ConfigProvider ([#354](#354)) ([29cc614](29cc614)) * Allows publishing npm versions from feature branches ([#186](#186)) ([044c117](044c117)) * Allows publishing on dev branch/distribution channel ([#162](#162)) ([39530fa](39530fa)) * allows UPS to receive cookie config options ([#261](#261)) ([8ab9ce9](8ab9ce9)) * ant design system ([#9](#9)) ([7c0f090](7c0f090)) * ant upgrade to 5.20 ([#421](#421)) ([49b4bf8](49b4bf8)) * components ([#33](#33)) ([78dfb17](78dfb17)) * Exports bundle without libs (React, Antd) and TS types ([#76](#76)) ([5dbb9df](5dbb9df)) * first story with a simple component and directory structure with readmes ([a60b9b8](a60b9b8)) * focus workspace on icon click ([#163](#163)) ([cea91cd](cea91cd)) * global navigation and styling ([#124](#124)) ([7863d9a](7863d9a)) * icons placeholder ([#385](#385)) ([2503af1](2503af1)) * **icons:** export icons from the Aquarium ([dde4db2](dde4db2)) * install vitest unit test runner ([#143](#143)) ([2ad4075](2ad4075)) * intial add of QueryItem.ValueSelector.Cascader ([c022aa2](c022aa2)) * minimap active state ([#263](#263)) ([ae9a2b0](ae9a2b0)) * move minimap to suite logo ([#369](#369)) ([f2d2437](f2d2437)) * new icons ([#239](#239)) ([a1bfb88](a1bfb88)) * New storybook documentation structure ([#419](#419)) ([1a870bc](1a870bc)) * Organize component directories by type ([#16](#16)) ([6ad046d](6ad046d)) * query select number ([#268](#268)) ([13dc864](13dc864)) * **queryitem:** adding onchange and converting error danger zone text ([91e945f](91e945f)) * **queryitem:** adding QueryItem.Qualifier component ([1fe60d8](1fe60d8)) * **queryitem:** updating styles and adding error message to qualifier ([fa8a8da](fa8a8da)) * replace minimap with suiteSelector component ([#383](#383)) ([2ab27ca](2ab27ca)) * rework Cascader OnChange ([a77c44f](a77c44f)) * Storybook Testing ([#42](#42)) ([876c231](876c231)) * Tag component stories ([#68](#68)) ([4831b25](4831b25)) * update design tokens ([#273](#273)) ([ac2b442](ac2b442)) * update SuiteLogo in GlobalNav to render nav switcher Tour ([#367](#367)) ([a3920af](a3920af)) * UPS code ported from Nancy ([#207](#207)) ([cc153af](cc153af)) * wrap radio group and button components ([#282](#282)) ([6e67439](6e67439))

tibuurcio added 5 commits September 18, 2024 15:54

feat: introducing new storybook structure

a4288c9

chore: new documentation pages

b273b97

chore: new documentation pages

f1e6590

chore: moving stories to the components section

739f05f

chore: latest changes in docs

74129b9

tibuurcio requested review from gabrielmarquesf, nastyastavitskaya, jared-dickman, gabyzif and danielsiemens September 18, 2024 19:19

tibuurcio added 3 commits September 18, 2024 16:36

chore: testing new preview workflow

ea9da7e

chore: update preview workflow to include GITHUB_TOKEN credentials

a31dcbe

chore: tries removing permissions from the workflow

c50124b

tibuurcio added 9 commits September 18, 2024 17:02

chore: trying the .nojekyll file creation approach

682ccd6

chore: trying a new publishing storybook workflow

6fee641

chore: trying to remove remark-gfm dependency to see if gh-pages disp…

924ba44

…lays it correctly

chore: back to old publishing workflow again

7b17923

chore: trying the preview.tsx approach

8191712

chore: adds remark-gfm dependency again

a3e59ea

chore: back again at newer version of publishing storybook workflow

331a5ad

chore: trying the .nojekyll approach again

defb539

chore: better names for workflows

5c3dc75

tibuurcio added 2 commits September 20, 2024 11:50

chore: addressing reviews

60678a5

chore: puts foundations in front of components in left nav

d3c12c5

tibuurcio commented Sep 20, 2024

View reviewed changes

chore: adds new Date Range Picker candidate component docs

71b9118

tibuurcio commented Sep 20, 2024

View reviewed changes

docs/Component Process/Candidate Components/Using existing ones.mdx Outdated

Copy link

Collaborator Author

tibuurcio Sep 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Example rendering a mermaid chart

tibuurcio added 4 commits September 25, 2024 17:37

chore: added date and removed example code for Date Range Filter

977140e

Merge branch 'main' into feat/new-storybook-structure

7028945

chore: adding some ts-expect-errors for component candidate stories

d212218

Merge branch 'feat/new-storybook-structure' of https://github.com/mPa…

a6cb11c

…rticle/aquarium into feat/new-storybook-structure

tibuurcio commented Sep 25, 2024

View reviewed changes

gabyzif approved these changes Sep 26, 2024

View reviewed changes

tibuurcio merged commit 1a870bc into main Sep 26, 2024
11 of 12 checks passed

mparticle-automation added the released on @fix label Sep 30, 2024

mparticle-automation added the released on @feature label Sep 30, 2024

mparticle-automation added the released label Sep 30, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: New storybook documentation structure #419

feat: New storybook documentation structure #419

tibuurcio commented Sep 18, 2024 •

edited

Loading

ilyusha commented Sep 18, 2024

github-actions bot commented Sep 18, 2024 •

edited

Loading

gabyzif commented Sep 19, 2024

tibuurcio commented Sep 20, 2024

tibuurcio Sep 20, 2024

tibuurcio Sep 20, 2024

tibuurcio Sep 20, 2024

tibuurcio Sep 20, 2024

tibuurcio Sep 25, 2024

tibuurcio Sep 25, 2024

gabyzif left a comment

mparticle-automation commented Sep 30, 2024

mparticle-automation commented Sep 30, 2024

mparticle-automation commented Sep 30, 2024

feat: New storybook documentation structure #419

feat: New storybook documentation structure #419

Conversation

tibuurcio commented Sep 18, 2024 • edited Loading

Summary

Reference Issue (For mParticle employees only. Ignore if you are an outside contributor)

ilyusha commented Sep 18, 2024

Review Forge

github-actions bot commented Sep 18, 2024 • edited Loading

gabyzif commented Sep 19, 2024

tibuurcio commented Sep 20, 2024

tibuurcio Sep 20, 2024

Choose a reason for hiding this comment

tibuurcio Sep 20, 2024

Choose a reason for hiding this comment

tibuurcio Sep 20, 2024

Choose a reason for hiding this comment

tibuurcio Sep 20, 2024

Choose a reason for hiding this comment

tibuurcio Sep 25, 2024

Choose a reason for hiding this comment

tibuurcio Sep 25, 2024

Choose a reason for hiding this comment

gabyzif left a comment

Choose a reason for hiding this comment

mparticle-automation commented Sep 30, 2024

mparticle-automation commented Sep 30, 2024

mparticle-automation commented Sep 30, 2024

tibuurcio commented Sep 18, 2024 •

edited

Loading

github-actions bot commented Sep 18, 2024 •

edited

Loading