From 033b0fe29f9202601455dfb5be5c92311d84a442 Mon Sep 17 00:00:00 2001
From: Sainath Poojary <spoojary614@gmail.com>
Date: Thu, 30 Jan 2025 14:07:49 +0530
Subject: [PATCH] FontAppearanceControl: Add JSDoc for FontAppearanceControl
---
.../font-appearance-control/README.md | 1 -
.../font-appearance-control/index.js | 45 +++++++++++++++++--
2 files changed, 42 insertions(+), 4 deletions(-)
diff --git a/packages/block-editor/src/components/font-appearance-control/README.md b/packages/block-editor/src/components/font-appearance-control/README.md
index 53a216b9c95393..991978c88a92a5 100644
--- a/packages/block-editor/src/components/font-appearance-control/README.md
+++ b/packages/block-editor/src/components/font-appearance-control/README.md
@@ -4,7 +4,6 @@ The `FontAppearanceControl` component renders a dropdown menu that displays font
This component is primarily used in typography-related block settings (e.g., Paragraph, Heading, etc.) where users need to adjust visual appearance of text elements. Available options vary based on the font's capabilities.
-
## Usage
Renders a font appearance selector with style/weight combinations.
diff --git a/packages/block-editor/src/components/font-appearance-control/index.js b/packages/block-editor/src/components/font-appearance-control/index.js
index 62396c2dc7bd64..e1592cc1ea4e7f 100644
--- a/packages/block-editor/src/components/font-appearance-control/index.js
+++ b/packages/block-editor/src/components/font-appearance-control/index.js
@@ -32,11 +32,50 @@ const getFontAppearanceLabel = ( hasFontStyles, hasFontWeights ) => {
};
/**
- * Control to display font style and weight options of the active font.
+ * The `FontAppearanceControl` component renders a dropdown menu that displays font style and weight options for the selected font family.
+ * This control dynamically adapts to show style/weight combinations supported by the active font.
*
- * @param {Object} props Component props.
+ * @since 6.8.0
*
- * @return {Element} Font appearance control.
+ * @example
+ * ```jsx
+ * import { FontAppearanceControl } from '@wordpress/block-editor';
+ *
+ * const MyFontAppearanceToolbar = () => {
+ * const [ fontAppearance, setFontAppearance ] = useState( {
+ * fontStyle: 'normal',
+ * fontWeight: '400',
+ * } );
+ *
+ * return (
+ * <FontAppearanceControl
+ * value={ fontAppearance }
+ * onChange={ ( newAppearance ) => {
+ * setFontAppearance( newAppearance );
+ * } }
+ * fontFamilyFaces={ availableFontFaces }
+ * hasFontStyles={ true }
+ * hasFontWeights={ true }
+ * __next40pxDefaultSize={ true }
+ * />
+ * );
+ * };
+ * ```
+ *
+ * @param {Object} props Component properties.
+ * @param {Object} props.value Current font appearance settings.
+ * @param {string} [props.value.fontStyle] The current font style value.
+ * @param {string} [props.value.fontWeight] The current font weight value.
+ * @param {Function} props.onChange Callback function invoked when selection changes. Receives an object with fontStyle and fontWeight properties.
+ * @param {boolean} [props.hasFontStyles=true] Whether to show font style options.
+ * @param {boolean} [props.hasFontWeights=true] Whether to show font weight options.
+ * @param {Array} props.fontFamilyFaces Array of font face objects containing available styles and weights.
+ * @param {Object} props.fontFamilyFaces[].style Font style for this face (e.g., 'normal', 'italic').
+ * @param {string} props.fontFamilyFaces[].weight Font weight for this face (e.g., '400', '700').
+ * @param {boolean} [props.__next40pxDefaultSize=false] Whether to opt into the larger default height
+ * that will become the default size in a future version.
+ * Will be default in version 7.1.
+ * @return {JSX.Element|null} The font appearance control component if styles or weights are available, null otherwise.
*/
export default function FontAppearanceControl( props ) {
const {