Add initial docs for the analysis-report package #21878
Open
+585
−0
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Pull Request Test Coverage Report for Build e1d7db12c0eb683296d24082f255725f3c30154cDetails
💛 - Coveralls |
mhkuu
requested changes
Nov 29, 2024
|
|
||
| ## Overview | ||
|
|
||
| This package provides React components to display the results of content analysis performed by the [@yoast/yoastseo](../yoastseo) package. It visualizes SEO scores, readability metrics, and improvement suggestions in an organized and user-friendly way. |
There was a problem hiding this comment.
Suggested change
| This package provides React components to display the results of content analysis performed by the [@yoast/yoastseo](../yoastseo) package. It visualizes SEO scores, readability metrics, and improvement suggestions in an organized and user-friendly way. | |
| This package provides React components to display the results of content analysis performed by the `yoastseo` package ([GitHub](../yoastseo), [NPM](https://www.npmjs.com/package/yoastseo)). It visualizes SEO scores, readability metrics, and improvement suggestions in an organized and user-friendly way. |
Comment on lines
+15
to
+19
| Note: This package has peer dependencies that need to be installed: | ||
| - react | ||
| - react-dom | ||
| - styled-components | ||
| - @wordpress/i18n |
There was a problem hiding this comment.
This bit can be removed in my opinion, they're not peer dependencies but actual dependencies.
| ``` | ||
|
|
||
| #### Features | ||
| - Sanitizes HTML in text content |
There was a problem hiding this comment.
Suggested change
| - Sanitizes HTML in text content | |
| - Sanitizes HTML in the analysis feedback |
Comment on lines
+228
to
+229
| C --> E[MarkerButtons] | ||
| C --> F[EditButton] |
There was a problem hiding this comment.
Suggested change
| C --> E[MarkerButtons] | |
| C --> F[EditButton] | |
| C --> E[Highlighting button] | |
| C --> F[Edit button (Premium)] | |
| C --> G[Yoast AI Optimize button (Premium)] |
| When using this package outside of WordPress, keep in mind: | ||
|
|
||
| 1. **Translations**: The package uses @wordpress/i18n for translations. You'll need to: | ||
| - Provide your own translation implementation |
There was a problem hiding this comment.
Suggested change
| - Provide your own translation implementation | |
| - Provide your own translation implementation when used outside of WordPress. The translations can be retrieved from https://translate.wordpress.org. |
| - Mock the i18n functions in tests | ||
| - Set up the translation infrastructure | ||
|
|
||
| 2. **Styling**: The package uses styled-components and expects certain theme variables: |
There was a problem hiding this comment.
Suggested change
| 2. **Styling**: The package uses styled-components and expects certain theme variables: | |
| 2. **Styling**: The package uses `styled-components` and expects certain theme variables: |
Comment on lines
+418
to
+573
| hasMarks: boolean; // Whether this result supports text marking | ||
| marker?: Marker; // Marking instructions | ||
| marksButtonStatus?: "enabled" | "disabled" | "hidden"; | ||
|
|
||
| // Edit functionality | ||
| hasEditButton: boolean; // Whether to show edit button | ||
| editFieldName?: string; // Field to focus when edit clicked | ||
|
|
||
| // Styling | ||
| bulletColor: string; // Color for score indicator | ||
| marksButtonClassName?: string; | ||
| editButtonClassName?: string; | ||
|
|
||
| // Accessibility | ||
| ariaLabelMarks: string; | ||
| ariaLabelEdit?: string; | ||
|
|
||
| // State | ||
| pressed: boolean; // Whether marks are active | ||
| suppressedText?: boolean;// Grey out the text | ||
| } | ||
| ``` | ||
|
|
||
| #### Features | ||
| - Sanitizes HTML in text content | ||
| - Manages button states and interactions | ||
| - Handles accessibility attributes | ||
| - Supports custom styling | ||
|
|
||
| ### SiteSEOReport | ||
|
|
||
| Displays aggregate SEO scores with a stacked progress bar visualization. | ||
|
|
||
| #### Props | ||
| ```typescript | ||
| interface SiteSEOReportProps { | ||
| className?: string; | ||
| seoAssessmentText: string; | ||
| seoAssessmentItems: Array<{ | ||
| html: string; // HTML content for item description | ||
| value: number; // Percentage value (0-100) | ||
| color: string; // Color for progress bar segment | ||
| }>; | ||
| barHeight?: string; // Custom height for progress bar | ||
| } | ||
| ``` | ||
|
|
||
| #### Features | ||
| - Renders stacked progress bars | ||
| - Displays score breakdowns | ||
| - Supports custom styling and dimensions | ||
| - Handles responsive layouts | ||
|
|
||
| ## Component Interactions | ||
|
|
||
| ### Data Flow | ||
| ```mermaid | ||
| sequenceDiagram | ||
| participant P as Parent App | ||
| participant C as ContentAnalysis | ||
| participant A as AnalysisResult | ||
| participant M as Marker System | ||
|
|
||
| P->>C: Analysis Results | ||
| C->>A: Individual Result | ||
| A->>M: Marking Request | ||
| M->>P: Mark Positions | ||
| P->>M: Apply Marks | ||
| M->>A: Update UI | ||
| ``` | ||
|
|
||
| ### State Management | ||
|
|
||
| The components follow a unidirectional data flow: | ||
|
|
||
| 1. **Parent Level** | ||
| ```javascript | ||
| { | ||
| activeMarker: string | null; // Currently active marker | ||
| marks: Mark[]; // Active text marks | ||
| results: AnalysisResult[]; // Analysis results | ||
| } | ||
| ``` | ||
|
|
||
| 2. **ContentAnalysis Level** | ||
| ```javascript | ||
| { | ||
| collapsibleStates: { // Section collapse states | ||
| [category: string]: boolean | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 3. **AnalysisResult Level** | ||
| ```javascript | ||
| { | ||
| isHovered: boolean; // UI hover state | ||
| isPressed: boolean; // Marker active state | ||
| } | ||
| ``` |
There was a problem hiding this comment.
I would remove these parts as they mostly repeat information from above.
There was a problem hiding this comment.
I'd definitely keep the sequence diagram, that's nice to have. This last State Management section I don't really understand, but seems different from what I read before as well.
d-claassen
reviewed
Dec 2, 2024
| ### ContentAnalysis | ||
| The main component that organizes analysis results into collapsible sections: | ||
|
|
||
| #### Props |
There was a problem hiding this comment.
There's a couple of props missing here. Maybe they're left out intentionally?
markButtonFactory, resultCategoryLabels, onResultChange, renderHighlightUpsell, renderAIFixesButton
| ### AnalysisResult | ||
| Individual result item with score indicator and optional marking functionality: | ||
|
|
||
| #### Props |
There was a problem hiding this comment.
There's a couple of props missing here too.
hasMarksButton, hasEditButton, hasAIButton, hasAIFixes, buttonIdMarks, buttonIdEdit, onButtonClickMarks, onButtonClickEdit, marksButtonFactory, hasBetaBadgeLabel, isPremium, onResultChange, shouldUpsellHighlighting, renderHighlightUpsell, renderAIFixesButton
| seoAssessmentText: string; | ||
| seoAssessmentItems: Array<{ | ||
| html: string; // HTML content for item description | ||
| value: number; // Percentage value (0-100) |
There was a problem hiding this comment.
This can be any numeric value, shouldn't be a percentage value. The SiteSEOReport uses the StackedProgressBar from @yoast/components which will sum all the value props of these items and determines a percentage afterwards. The values should be positives, negative values will be considered to be 0. Note these values are also used for the score breakdown.
| ## Example Integration | ||
|
|
||
| ```jsx | ||
| import { ContentAnalysis, AnalysisResult } from "@yoast/analysis-report"; |
There was a problem hiding this comment.
The AnalysisResult isn't used in this example.
Suggested change
| import { ContentAnalysis, AnalysisResult } from "@yoast/analysis-report"; | |
| import { ContentAnalysis } from "@yoast/analysis-report"; |
| } | ||
| ``` | ||
|
|
||
| ## Components Reference |
There was a problem hiding this comment.
This section is pretty much a duplicate of the Core Components section, except from the component descriptions that are slightly more detailed here.
Comment on lines
+418
to
+573
| hasMarks: boolean; // Whether this result supports text marking | ||
| marker?: Marker; // Marking instructions | ||
| marksButtonStatus?: "enabled" | "disabled" | "hidden"; | ||
|
|
||
| // Edit functionality | ||
| hasEditButton: boolean; // Whether to show edit button | ||
| editFieldName?: string; // Field to focus when edit clicked | ||
|
|
||
| // Styling | ||
| bulletColor: string; // Color for score indicator | ||
| marksButtonClassName?: string; | ||
| editButtonClassName?: string; | ||
|
|
||
| // Accessibility | ||
| ariaLabelMarks: string; | ||
| ariaLabelEdit?: string; | ||
|
|
||
| // State | ||
| pressed: boolean; // Whether marks are active | ||
| suppressedText?: boolean;// Grey out the text | ||
| } | ||
| ``` | ||
|
|
||
| #### Features | ||
| - Sanitizes HTML in text content | ||
| - Manages button states and interactions | ||
| - Handles accessibility attributes | ||
| - Supports custom styling | ||
|
|
||
| ### SiteSEOReport | ||
|
|
||
| Displays aggregate SEO scores with a stacked progress bar visualization. | ||
|
|
||
| #### Props | ||
| ```typescript | ||
| interface SiteSEOReportProps { | ||
| className?: string; | ||
| seoAssessmentText: string; | ||
| seoAssessmentItems: Array<{ | ||
| html: string; // HTML content for item description | ||
| value: number; // Percentage value (0-100) | ||
| color: string; // Color for progress bar segment | ||
| }>; | ||
| barHeight?: string; // Custom height for progress bar | ||
| } | ||
| ``` | ||
|
|
||
| #### Features | ||
| - Renders stacked progress bars | ||
| - Displays score breakdowns | ||
| - Supports custom styling and dimensions | ||
| - Handles responsive layouts | ||
|
|
||
| ## Component Interactions | ||
|
|
||
| ### Data Flow | ||
| ```mermaid | ||
| sequenceDiagram | ||
| participant P as Parent App | ||
| participant C as ContentAnalysis | ||
| participant A as AnalysisResult | ||
| participant M as Marker System | ||
|
|
||
| P->>C: Analysis Results | ||
| C->>A: Individual Result | ||
| A->>M: Marking Request | ||
| M->>P: Mark Positions | ||
| P->>M: Apply Marks | ||
| M->>A: Update UI | ||
| ``` | ||
|
|
||
| ### State Management | ||
|
|
||
| The components follow a unidirectional data flow: | ||
|
|
||
| 1. **Parent Level** | ||
| ```javascript | ||
| { | ||
| activeMarker: string | null; // Currently active marker | ||
| marks: Mark[]; // Active text marks | ||
| results: AnalysisResult[]; // Analysis results | ||
| } | ||
| ``` | ||
|
|
||
| 2. **ContentAnalysis Level** | ||
| ```javascript | ||
| { | ||
| collapsibleStates: { // Section collapse states | ||
| [category: string]: boolean | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 3. **AnalysisResult Level** | ||
| ```javascript | ||
| { | ||
| isHovered: boolean; // UI hover state | ||
| isPressed: boolean; // Marker active state | ||
| } | ||
| ``` |
There was a problem hiding this comment.
I'd definitely keep the sequence diagram, that's nice to have. This last State Management section I don't really understand, but seems different from what I read before as well.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Context
We are lacking documentation on how to use some of the packages that are meant to be shared across platforms/projects. One of these packages is the
analysis-reportpackage.This PR creates an initial
README.mdfile for that package.Summary
This PR can be summarized in the following changelog entry:
packages/analysis-report/README.mdfile with a documentation overviewRelevant technical choices: