Merge pull request #379 from infinum/feature/ui-components-docs-update

ES UI components docs updates

Author: goranalkovic-infinum

website/bun.lock

@@ -34,10 +34,10 @@
 	"dependencies": {
 		"@docusaurus/core": "^3.9.2",
 		"@docusaurus/preset-classic": "^3.9.2",
-		"@eightshift/ui-components": "^5.2.0",
+		"@eightshift/ui-components": "^6.2.0",
 		"@infinum/docusaurus-theme": "^0.6.0",
-		"@mdx-js/react": "^3.1.0",
-		"@wp-playground/client": "^2.0.3",
+		"@mdx-js/react": "^3.1.1",
+		"@wp-playground/client": "^2.0.22",
 		"clsx": "^2.1.1",
 		"es-text-loader": "file:plugins/es-text-loader",
 		"prism-react-renderer": "^2.4.1",

website/package.json

@@ -20,7 +20,7 @@ export const ComponentShowcase = ({
 				<div className='es:flex es:font-sans es:css-reset'>
 					<div
 						className={clsx(
-							'es:border es:border-dashed es:border-gray-200 es:p-4 es:rounded-lg esd-space-v es:shrink-0 esd-showcase',
+							'es:border es:border-dashed es:border-secondary-200 es:p-4 es:rounded-lg esd-space-v es:shrink-0 esd-showcase',
 							fitWidth ? 'es:w-fit' : 'esd-showcase-w',
 							className
 						)}
@@ -29,7 +29,7 @@ export const ComponentShowcase = ({
 						{typeof children !== 'function' && children}
 					</div>
 
-					<div className='esd-space-v es:ml-3 es:grow'>
+					<div className='esd-space-v es:pl-4 es:grow'>
 						{preContent && preContent(data, setData, ref)}
 						{resettable && (
 							<Button

website/ui-components/components/component-showcase.js

@@ -10,11 +10,31 @@ import { demoGetData } from './select-helpers';
 		<AsyncMultiSelect
 			value={data}
 			onChange={setData}
-			loadOptions={demoGetData}
+			fetchFunction={demoGetData}
 		/>
 	)}
 </ComponentShowcase>
 
+## Default data fetching
+
+To define how label, value, subtitle (optional), and icon (optional) are defined in the options, use `getLabel`, `getValue`, `getSubtitle`, `getIcon`.
+
+```jsx
+<AsyncMultiSelect
+	value={value}
+	onChange={(value) => setValue(value)}
+	fetchUrl={(searchText) =>
+		searchText?.length >= 3 ? `http://example-api.com?limit=5&search=${searchText}` : 'http://example-api.com?limit=5'
+	}
+	getLabel={(item) => item?.name}
+	getValue={(item) => item?.id}
+/>
+```
+
+## Alternate data fetching
+
+Provide a function that fetches data asynchronously and returns it in the format of an array of objects with `label` and `value` properties.
+
 ```jsx
 const getOptions = async () => {
 	...
@@ -23,13 +43,13 @@ const getOptions = async () => {
 <AsyncMultiSelect
 	value={value}
 	onChange={(value) => setValue(value)}
-	loadOptions={getOptions}
+	fetchFunction={getOptions}
 />
 ```
 
 :::note
 Props are mostly the same as for the [Single select](/components/es-ui-components/select),
-with the exceptions of `options` (which is replaced with `loadOptions`) and `simpleValue`, which is not supported.
+with the exceptions of `options` (which is replaced with `fetchFunction`) and `simpleValue`, which is not supported.
 :::
 
 For the complete list of props, use your IDE's autocomplete functionality.

website/ui-components/es-ui-components/async-multi-select.mdx

@@ -10,11 +10,31 @@ import { demoGetData } from './select-helpers';
 		<AsyncSelect
 			value={data}
 			onChange={setData}
-			loadOptions={demoGetData}
+			fetchFunction={demoGetData}
 		/>
 	)}
 </ComponentShowcase>
 
+## Default data fetching
+
+To define how label, value, subtitle (optional), and icon (optional) are defined in the options, use `getLabel`, `getValue`, `getSubtitle`, `getIcon`.
+
+```jsx
+<AsyncSelect
+	value={value}
+	onChange={(value) => setValue(value)}
+	fetchUrl={(searchText) =>
+		searchText?.length >= 3 ? `http://example-api.com?limit=5&search=${searchText}` : 'http://example-api.com?limit=5'
+	}
+	getLabel={(item) => item?.name}
+	getValue={(item) => item?.id}
+/>
+```
+
+## Alternate data fetching
+
+Provide a function that fetches data asynchronously and returns it in the format of an array of objects with `label` and `value` properties.
+
 ```jsx
 const getOptions = async () => {
 	...
@@ -23,13 +43,13 @@ const getOptions = async () => {
 <AsyncSelect
 	value={value}
 	onChange={(value) => setValue(value)}
-	loadOptions={getOptions}
+	fetchFunction={getOptions}
 />
 ```
 
 :::note
 Props are mostly the same as for the [Single select](/components/es-ui-components/select),
-with the exceptions of `options` (which is replaced with `loadOptions`) and `simpleValue`, which is not supported.
+with the exceptions of `options` (which is replaced with `fetchFunction`) and `simpleValue`, which is not supported.
 :::
 
 For the complete list of props, use your IDE's autocomplete functionality.

website/ui-components/es-ui-components/async-select.mdx

@@ -4,6 +4,8 @@ import { ComponentShowcase } from '../components/component-showcase';
 import { Button, InputField } from '@eightshift/ui-components';
 import { icons, blockIcons, BlockIcon } from '@eightshift/ui-components/icons';
 
+Use within block manifests, or in your UI with the `<BlockIcon />` component.
+
 <ComponentShowcase
 	className='es:flex es:flex-wrap es:gap-2 !es:space-y-0 es:w-full'
 	fitWidth
@@ -22,24 +24,25 @@ import { icons, blockIcons, BlockIcon } from '@eightshift/ui-components/icons';
 			data?.length > 0 ? k.toLowerCase().includes(data?.toLowerCase()) : true
 		);
 
-    	if (filteredIcons.length < 1)  {
-    		return (
-    			<span>Nothing found</span>
-    		);
-    	}
+		if (filteredIcons.length < 1)  {
+			return (
+				<span>Nothing found</span>
+			);
+		}
 
-    	return filteredIcons.map((icon, index) => (
-    		<Button
-    			key={index}
-    			className='esd-icon-showcase-button'
-    			icon={<BlockIcon iconName={icon} />}
-    			tooltip={<span className='es:font-mono'>{icon}</span>}
-    			aria-label={icon}
-    			onPress={() => {
-    				navigator.clipboard.writeText(icon);
-    			}}
-    		/>
-    	));
-    }}
+		return filteredIcons.map((icon, index) => (
+			<Button
+				key={index}
+				className='esd-icon-showcase-button'
+				icon={<BlockIcon iconName={icon} />}
+				tooltip={<span className='es:font-mono'>{icon}</span>}
+				aria-label={icon}
+				onPress={() => {
+					navigator.clipboard.writeText(icon);
+				}}
+				type='simple'
+			/>
+		));
+	}}
 
 </ComponentShowcase>

website/ui-components/es-ui-components/block-icons.mdx

@@ -59,7 +59,7 @@ export const DraggableDemo = ({ data, setData, ...rest }) => {
 		<Draggable
 			items={data}
 			onChange={setData}
-			className='es:grid es:grid-cols-2'
+			className='es:grid es:grid-cols-2 es:gap-2'
 			{...rest}
 		>
 			{(item) => {

website/ui-components/es-ui-components/draggable-list-helpers.js

@@ -13,49 +13,60 @@ At the minimum you have to import the main styles, which come in 3 flavors:
 
 1. *For generic usage*
 ```scss
-@import '~@eightshift/ui-components/dist/assets/style.css';
+@import '@eightshift/ui-components/dist/assets/style.css';
 ```
 Uses cascade layers to separate styles, includes the default CSS reset.
 
-2. *For the WP Gutenberg editor*
+2. *For the WP Gutenberg editor* in legacy projects
  ```scss
-@import '~@eightshift/ui-components/dist/assets/style-editor.css';
+@import '@eightshift/ui-components/dist/assets/style-editor.css';
 ```
 Cascade layers are not used, CSS reset is included.
 
 3. *For the WP admin area*
 ```scss
-@import '~@eightshift/ui-components/dist/assets/style-admin.css';
+@import '@eightshift/ui-components/dist/assets/style-admin.css';
 ```
 Cascade layers are not used, CSS reset is opt-in using the `es:css-reset` class.
 
 #### Extras
 To expand the font coverage to the Block editor (even the Gutenberg components), import:
 ```scss
-@import '~@eightshift/ui-components/dist/assets/wp-font-enhancements.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/replace-fonts.css';
 ```
 
-Optionally, import the WordPress UI enhancements, which correct some of the inconsistencies in the default components.
+Optionally, import (some or all of) the WordPress UI enhancements, which correct some of the inconsistencies in the default components.
 
 ```scss
-@import '~@eightshift/ui-components/dist/assets/wp-ui-enhancements.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/fix-label-text-case.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/increase-sidebar-width.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/make-block-messages-nicer.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/restyle-tooltips.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/round-corners.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/unify-button-sizes.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/allow-full-width-blocks.css';
 ```
 
-:::caution
 If using Frontend libs version 12 or older, skip the WordPress UI enhancements, as they will conflict with the styles included there.
-:::
 
 #### Recommended WordPress setup
 `application-blocks-editor.css`
 ```scss
-@import '~@eightshift/ui-components/dist/assets/wp-font-enhancements.css';
-@import '~@eightshift/ui-components/dist/assets/wp-ui-enhancements.css';
-@import '~@eightshift/ui-components/dist/assets/style-editor.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/replace-fonts.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/fix-label-text-case.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/increase-sidebar-width.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/make-block-messages-nicer.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/restyle-tooltips.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/round-corners.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/unify-button-sizes.css';
+@import '@eightshift/ui-components/dist/assets/wp-overrides/allow-full-width-blocks.css';
+
+@import '@eightshift/ui-components/dist/assets/style.css'; // or style-editor.css for non-Tailwind projects
 ```
 
 `application-admin.css`
 ```scss
-@import '~@eightshift/ui-components/dist/assets/style-admin.css';
+@import '@eightshift/ui-components/dist/assets/style-admin.css';
 ```
 
 ### Enjoy!

website/ui-components/es-ui-components/getting-started.mdx

@@ -1,6 +1,51 @@
 # Migrations
+
 Here's how to upgrade between various versions of ES UI components.
 
+## v5.x.x to v6.x.x
+
+1. Update the package to the latest version.
+
+2. Update CSS imports for UI components styles.
+
+Font enhancements:
+
+```diff
+- @eightshift/ui-components/dist/assets/wp-font-enhancements.css
++ @eightshift/ui-components/dist/assets/wp-overrides/replace-fonts.css
+```
+
+General style tweaks/overrides (now modular, pick&choose enhancements you want):
+
+```diff
+- @eightshift/ui-components/dist/assets/wp-ui-enhancements.css
++ @eightshift/ui-components/dist/assets/wp-overrides/fix-label-text-case.css
++ @eightshift/ui-components/dist/assets/wp-overrides/increase-sidebar-width.css
++ @eightshift/ui-components/dist/assets/wp-overrides/make-block-messages-nicer.css
++ @eightshift/ui-components/dist/assets/wp-overrides/restyle-tooltips.css
++ @eightshift/ui-components/dist/assets/wp-overrides/round-corners.css
++ @eightshift/ui-components/dist/assets/wp-overrides/unify-button-sizes.css
++ @eightshift/ui-components/dist/assets/wp-overrides/allow-full-width-blocks.css
+```
+
+3. Selects
+
+Check all `Select`, `AsyncSelect`, `MultiSelect`, `AsyncMultiSelect` components, remove any references to legacy `react-select` components (name starting with `RS`)
+
+`AsyncSelect`/`AsyncMultiSelect`: change `loadOptions` prop for `fetchFunction`.
+
+4. `ComponentToggle`
+
+If used, try to replace with a `Toggle` and conditional rendering. The component _is_ marked as deprecated, but won't be removed until v7.
+
+5. Misc. minor updates:
+
+- `ContainerPanel` <br/> Re-add `topBorder` if desired
+- `Tabs` <br/> Replace `pillInverse`, `pillCompactInverse`, `pillOutline`, and `pillCompactOutline` styles if used
+- `OptionsPanelIntro` <br/> Remove `border` prop if set
+- `NumberPicker` <br/> Update values for the `size` prop if set; `'compact' | 'small' | 'default'` &rarr; `'small' | 'medium' | 'default' | 'large'`
+- `NumberPicker` <br/> If using `<Button>` as a custom control within, add `slot={null}`
+
 ## v1.x.x to v2.0.1
 
 1. Update the package to the latest version.
@@ -14,13 +59,15 @@ Here's how to upgrade between various versions of ES UI components.
 2. Replace editor imports
 
 `application-blocks-editor.css`
+
 ```diff
 @import '~@eightshift/ui-components/dist/assets/wp-font-enhancements.css';
 - @import '~@eightshift/ui-components/dist/assets/style.css';
 + @import '~@eightshift/ui-components/dist/assets/style-editor.css';
 ```
 
 `application-admin.css`
+
 ```diff
 - @import '~@eightshift/ui-components/dist/assets/style.css';
 + @import '~@eightshift/ui-components/dist/assets/style-admin.css';