feat(docs): add utility examples (#1867)

* feat(docs and test harnesses): switch test property to tags that includes 'test' for search * fix(core): enum cannot be exported as a type * chore(deps): bump lerna, @types/node, eslint-plugin-jsdoc, angular, dompurify, @carbon/*, vitest, highlight.js, vue-tsc * fix(stackblitz): margins * feat(docs/utility): add utility examples * fix(docs/area/example): type error
carbon-design-system · Jul 9, 2024 · 026e12a · 026e12a
1 parent 2b2ac7a
commit 026e12a
Show file tree

Hide file tree

Showing 56 changed files with 1,893 additions and 841 deletions.
diff --git a/package.json b/package.json
@@ -25,28 +25,28 @@
 		"@eslint/compat": "^1.1.0",
 		"@eslint/js": "^9.6.0",
 		"@playwright/test": "^1.45.1",
-		"@types/node": "^20.14.9",
+		"@types/node": "^20.14.10",
 		"@vue/eslint-config-prettier": "^9.0.0",
 		"@vue/eslint-config-typescript": "^13.0.0",
 		"eslint": "^9.6.0",
 		"eslint-config-prettier": "^9.1.0",
-		"eslint-plugin-jsdoc": "^48.5.0",
+		"eslint-plugin-jsdoc": "^48.5.2",
 		"eslint-plugin-prettier": "^5.1.3",
 		"eslint-plugin-react": "^7.34.3",
 		"eslint-plugin-react-hooks": "next",
 		"eslint-plugin-svelte": "^2.41.0",
 		"eslint-plugin-vue": "^9.27.0",
 		"globals": "^15.8.0",
 		"husky": "^9.0.11",
-		"lerna": "^8.1.5",
+		"lerna": "^8.1.6",
 		"lint-staged": "^15.2.7",
 		"prettier": "^3.3.2",
 		"prettier-config-carbon": "^0.11.0",
 		"prettier-plugin-svelte": "^3.2.5",
 		"svelte": "^4.2.18",
 		"svelte-eslint-parser": "^0.39.2",
 		"typescript": "^5.5.3",
-		"typescript-eslint": "^7.15.0",
+		"typescript-eslint": "^7.16.0",
 		"vue-eslint-parser": "^9.4.3"
 	},
 	"release": {

diff --git a/packages/angular/charts-angular-test/src/app/app.component.html b/packages/angular/charts-angular-test/src/app/app.component.html
@@ -4,7 +4,7 @@ <h2>Component Test Harness</h2>
 <div *ngFor="let chart of charts" class="container">
 	<h3>{{ chart.types.angular }}</h3>
 	<div *ngFor="let example of chart.examples" class="example">
-		<ng-container *ngIf="example.test">
+		<ng-container *ngIf="example.tags?.includes('test')">
 			<ng-container
 				*ngComponentOutlet="
 					selectorMap[chart.types.angular];

diff --git a/packages/angular/package.json b/packages/angular/package.json
@@ -34,13 +34,13 @@
 	"devDependencies": {
 		"@angular-devkit/build-angular": "^18.0.7",
 		"@angular/cli": "^18.0.7",
-		"@angular/common": "^18.0.5",
-		"@angular/compiler": "^18.0.5",
-		"@angular/compiler-cli": "^18.0.5",
-		"@angular/core": "^18.0.5",
-		"@angular/platform-browser": "^18.0.5",
-		"@angular/platform-browser-dynamic": "^18.0.5",
-		"@carbon/icons": "^11.44.1",
+		"@angular/common": "^18.0.6",
+		"@angular/compiler": "^18.0.6",
+		"@angular/compiler-cli": "^18.0.6",
+		"@angular/core": "^18.0.6",
+		"@angular/platform-browser": "^18.0.6",
+		"@angular/platform-browser-dynamic": "^18.0.6",
+		"@carbon/icons": "^11.45.0",
 		"@playwright/test": "^1.45.1",
 		"angular-eslint": "^18.1.0",
 		"concurrently": "^8.2.2",

diff --git a/packages/core/index.html b/packages/core/index.html
@@ -37,7 +37,7 @@ <h2>Component Test Harness</h2>
 				chartHolder.appendChild(header)
 
 				for (const example of chart.examples) {
-					if (example.test) {
+					if (example.tags && example.tags.includes('test')) {
 						const chartContainer = document.createElement('div')
 						chartContainer.className = 'chart-container'
 						chartHolder.appendChild(chartContainer)

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -80,15 +80,15 @@
 		"d3-cloud": "^1.2.7",
 		"d3-sankey": "^0.12.3",
 		"date-fns": "^3.6.0",
-		"dompurify": "^3.1.5",
+		"dompurify": "^3.1.6",
 		"html-to-image": "^1.11.11",
 		"lodash-es": "^4.17.21",
 		"topojson-client": "^3.1.0",
 		"tslib": "^2.6.3"
 	},
 	"devDependencies": {
 		"@carbon/layout": "^11.23.1",
-		"@carbon/styles": "^1.60.1",
+		"@carbon/styles": "^1.61.0",
 		"@carbon/themes": "^11.37.1",
 		"@playwright/test": "^1.45.1",
 		"@rollup/plugin-replace": "^5.0.7",
@@ -97,7 +97,7 @@
 		"@types/d3-sankey": "^0.12.4",
 		"@types/dompurify": "^3.0.5",
 		"@types/lodash-es": "^4.17.12",
-		"@types/node": "^20.14.9",
+		"@types/node": "^20.14.10",
 		"@types/topojson": "^3.2.6",
 		"concurrently": "^8.2.2",
 		"downlevel-dts": "^0.11.0",
@@ -110,7 +110,7 @@
 		"typescript": "^5.5.3",
 		"vite": "^5.3.3",
 		"vite-plugin-dts": "^3.9.1",
-		"vitest": "^1.6.0"
+		"vitest": "^2.0.1"
 	},
 	"publishConfig": {
 		"access": "public"

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -114,7 +114,6 @@ export type {
 	// Formats
 	TickFormats,
 	TimeIntervalFormats,
-	TimeIntervalNames,
 	// Other
 	Coordinates,
 	LegendItem,
@@ -166,6 +165,7 @@ export {
 	TextAnchor,
 	ThresholdEvent,
 	TickRotations,
+	TimeIntervalNames,
 	ToolbarControlTypes,
 	TooltipEvent,
 	TruncationTypes,

diff --git a/packages/core/src/interfaces/index.ts b/packages/core/src/interfaces/index.ts
@@ -8,10 +8,11 @@ export type {
 	ComboChartAxisOptions,
 	TickFormats,
 	TimeIntervalFormats,
-	TimeIntervalNames,
 	TimeScaleOptions
 } from './axis-scales'
 
+export { TimeIntervalNames } from './axis-scales'
+
 export type {
 	AlluvialChartOptions,
 	AreaChartOptions,

diff --git a/packages/docs/package.json b/packages/docs/package.json
@@ -20,10 +20,10 @@
 	"dependencies": {
 		"@carbon/charts": "workspace:*",
 		"@carbon/charts-react": "workspace:*",
-		"@carbon/icons-react": "^11.44.1",
-		"@carbon/react": "^1.60.3",
+		"@carbon/icons-react": "^11.45.0",
+		"@carbon/react": "^1.61.0",
 		"@stackblitz/sdk": "^1.11.0",
-		"highlight.js": "^11.9.0",
+		"highlight.js": "^11.10.0",
 		"react": "^18.3.1",
 		"react-dom": "^18.3.1",
 		"react-router-dom": "^6.24.1"

diff --git a/packages/docs/src/charts.ts b/packages/docs/src/charts.ts
@@ -34,7 +34,7 @@ import { chartTypes as treeTypes, examples as treeExamples } from './lib/tree'
 import { chartTypes as treemapTypes, examples as treemapExamples } from './lib/treemap'
 import { chartTypes as wordcloudTypes, examples as wordcloudExamples } from './lib/wordcloud'
 
-export default [
+const charts = [
 	{
 		types: alluvialTypes,
 		examples: alluvialExamples
@@ -136,3 +136,14 @@ export default [
 		examples: wordcloudExamples
 	}
 ]
+
+export default charts
+
+export function filterByTag(tag: string) {
+	return charts
+		.map(chart => ({
+			...chart,
+			examples: chart.examples.filter(example => example.tags && example.tags.includes(tag))
+		}))
+		.filter(chart => chart.examples.length > 0)
+}
diff --git a/packages/docs/src/components/ConfigExamples.tsx b/packages/docs/src/components/ConfigExamples.tsx
@@ -0,0 +1,32 @@
+import React from 'react'
+import * as ChartComponents from '@carbon/charts-react'
+import StackBlitzLauncher from './StackBlitzLauncher'
+import { filterByTag } from '../charts'
+
+interface ConfigExampleProps {
+	tag: string
+}
+
+export default function ConfigExample({ tag }: ConfigExampleProps) {
+	const examples = filterByTag(tag)
+
+	return (
+		<>
+			{examples.map((chart, chartIndex) => {
+				const ChartComponent = ChartComponents[
+					chart.types.react as keyof typeof ChartComponents
+				] as React.ComponentType<any>
+				return (
+					<div key={chartIndex}>
+						{chart.examples.map((example, exampleIndex) => (
+							<p key={exampleIndex} className="chart">
+								<ChartComponent data={example.data} options={example.options} />
+								<StackBlitzLauncher example={example} chartTypes={chart.types} />
+							</p>
+						))}
+					</div>
+				)
+			})}
+		</>
+	)
+}
diff --git a/packages/docs/src/components/ConfigPage.tsx b/packages/docs/src/components/ConfigPage.tsx
@@ -0,0 +1,22 @@
+import PageHeader from './PageHeader'
+import ConfigExamples from './ConfigExamples'
+
+interface UtilityExampleProps {
+	title: string
+	overview: string
+	tag: string
+}
+
+export default function UtilityExample({ title, overview, tag }: UtilityExampleProps) {
+	return (
+		<>
+			<PageHeader title={title} />
+
+			<h2>Overview</h2>
+
+			<p>{overview}</p>
+
+			<ConfigExamples tag={tag} />
+		</>
+	)
+}
diff --git a/packages/docs/src/components/DocsSideNav.tsx b/packages/docs/src/components/DocsSideNav.tsx
@@ -34,6 +34,24 @@ const DocsSideNav: React.FC<Props> = ({ isSideNavExpanded }) => (
 				<SideNavMenuItem as={NavLink} to="/options">
 					Chart display options
 				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/highlights">
+					Highlights
+				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/locales">
+					Locales
+				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/thresholds">
+					Thresholds
+				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/toolbar">
+					Toolbar customization
+				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/truncation">
+					Truncation
+				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/zoombar">
+					Zoombar
+				</SideNavMenuItem>
 				<SideNavMenuItem as={NavLink} to="/api">
 					API
 				</SideNavMenuItem>
@@ -52,6 +70,9 @@ const DocsSideNav: React.FC<Props> = ({ isSideNavExpanded }) => (
 				<SideNavMenuItem as={NavLink} to="/dashboards">
 					Dashboards
 				</SideNavMenuItem>
+				<SideNavMenuItem as={NavLink} to="/legends">
+					Legends
+				</SideNavMenuItem>
 			</SideNavMenu>
 			<SideNavDivider />
 			<SideNavMenu title="Chart types" defaultExpanded={true}>

diff --git a/packages/docs/src/components/StackBlitzLauncher.scss b/packages/docs/src/components/StackBlitzLauncher.scss
@@ -1,5 +1,7 @@
 .launch-buttons {
 	background-color: black;
+	margin-left: 2px;
+	margin-right: 2px;
 	button {
 		background-color: black;
 	}

diff --git a/packages/docs/src/lib/alluvial/index.ts b/packages/docs/src/lib/alluvial/index.ts
@@ -352,31 +352,31 @@ export const examples: Example[] = [
 	{
 		data,
 		options,
-		test: true
+		tags: ['test']
 	},
 	{
 		data,
 		options: optionsGradient,
-		test: true
+		tags: ['test']
 	},
 	{
 		data: dataMultipleCategories,
 		options: optionsMultipleCategories,
-		test: true
+		tags: ['test']
 	},
 	{
 		data: dataMonochrome,
 		options: optionsMonochrome,
-		test: true
+		tags: ['test', 'colors']
 	},
 	{
 		data: dataAligned,
 		options: optionsAligned,
-		test: true
+		tags: ['test']
 	},
 	{
 		data,
 		options: optionsCustomColors,
-		test: true
+		tags: ['test', 'colors']
 	}
 ]