KCardGrid part 2: Add KCardGrid with the base layouts + Add selection controls + Final documentation for KCard and KCardGrid + Few KCard bugfixes and improvements #785

MisRob · 2024-09-17T18:23:36Z

Description

`KCard` bugfixes, visual and public API updates

Adds support for selection controls such as checkboxes
Updates related to spaces between sections:
- Aligns spaces more closely to designs
- Introduces more robust spacing technique to ensures spaces are rendered as expected no matter of whether some/all/none slots are displayed
- Improves calculations coordinating space taken by the thumbnail and other content in the horizontal orientation so that no free space is wasted (progressive update taking effect in browsers that support clamp())

Before	After

Hides the placeholder after the thumbnail image is loaded
Renames titleLines prop to titleMaxLines
Renames layout prop to orientation

`KCardGrid`

Introduces KCardGrid with the base layouts
KCard updates to make screen readers announce only card titles when navigating the grid with TAB key

Docs

Organizes and adds more guidance for KCard docs
Adds new KCardGrid docs
New documentation components to help with organizing larger amounts of guidance: DocsSubNav, DocsToggleButton, DocsToggleContent, DocsTable
Slightly increases the width of the main documentation area to better demonstrate grids

Also has some minor cleanup.

See details and reasons for changes in commit messages.

References

Figma card grid designs - the three KCardGrid base layouts correspond to the (currently) only grid layouts we will use, and designs also demonstrate why grids are based on window breakpoints in contrast to available space in the containing element (however I think that may potentially be a valuable future improvement to be considered)
Builds on [BETA] Card grid and checkboxes #748
Closes Add new design pattern documentation page for cards #264
Closes Add more guidance to KCard docs #696
Closes KCardGrid MVP and specification #697
Closes KCard: Allow the height of sections to be configured and related improvements #703

Changelog

TODO @MisRob

Description: Summary of change(s)
Products impact: Choose from - none (for internal updates) / bugfix / new API / updated API / removed API. If it's 'none', use "-" for all items below to indicate they are not relevant.
Addresses: Link(s) to GH issue(s) addressed. Include KDS links as well as links to related issues in a consumer product repository too.
Components: Affected public KDS component. Do not include internal sub-components or documentation components.
Breaking: Will this change break something in a consumer? Choose from: yes / no
Impacts a11y: Does this change improve a11y or adds new features that can be used to improve it? Choose from: yes / no
Guidance: Why and how to introduce this update to a consumer? Required for breaking changes, appreciated for changes with a11y impact, and welcomed for non-breaking changes when relevant.

Steps to test

Read both documentation pages for KCard and KCardGrid
- Is all guidance clear?
- Is there some missing guidance?
Test live examples on both documentation pages
- Preview resulting markup
- Try keyboard navigation
- Try screen reader output

I can also provide a copy of the playground page with all visual layouts. However now when there's many live examples on documentation pages, for the purpose of review it would make more sense to use them as they offer larger variety regarding card content.

Testing checklist

Contributor has fully tested the PR manually
If there are any front-end changes, before/after screenshots are included
Critical and brittle code paths are covered by unit tests
The change is described in the changelog section above

Reviewer guidance

Is the code clean and well-commented?
Are there tests for this change?
Are all UI components LTR and RTL compliant (if applicable)?
Add other things to check for here

Comments

This PR completes all main pieces currently needed in Kolibri and Studio. After it's merged, we can close [BETA] Card grid and checkboxes #748 and link to KDS latest release.
Next PRs in the series will introduce useKCardGrid for advanced grid customization and loading states

to have a suitable location for playground sub-components when testing complex scenarios

alongside the existing very small picture to allow for testing in both cases.

to visually separate it from the footer slot.

to allow components that required more space to demonstrate their function in relevant ways, such as grids.

Ensures spaces are rendered as expected no matter of whether some/all/none slots are displayed. Also aligns spaces more closely to designs.

and use constants to define thumbnail width so they can be later referenced instead of hardcoded values..

the content area next to it more intelligently in browsers that support `clamp()` by: - Instead of defining 'width', 'min-width', and 'max-width' separately, `clamp()` is used with the goal to have the actual thumbnail width saved in the single `$thumbnail-width` value. - The `$thumbnail-width` value is then referenced when calculating the remaining space for the content area, ensuring the precise distribution of space. Resolves some issues related to unprecise calculations, most importantly this removes the area of empty space between the thumbnail and content areas in some card's sizes, wasting space that can be used for card's textual content.

Otherwise in some scenarios, such as when there is a large placeholder element and a small thumbnail image, some parts of the placeholder element may be visible behind the image after it has been successfully loaded.

to communicate its function more clearly

to communicate its purpose. The card layout is rather a combination of its orientation and the thumbnail area configuration.

when navigating the list of cards with TAB key. This resolves overwhelming output and aligns the screenreader navigation to the expected experience when on TAB only card titles should be announced (other content is still accessible by navigating with arrows). The main culprit that caused all content of cards being announced was 'tabindex=0' set on <li>. To resolve the problem, an alternative technique that doesn't require this tabindex is used to make the focus ring display around the whole card area.

by screenreaders and add some docs.

This information, with more, is now documented in the main documentaton sections.

MisRob · 2024-09-17T19:16:50Z

@radina Regarding checkboxes toggling working only with SPACE but not ENTER, I noticed ENTER is not working on our KCheckboxes in general. So if that was expected experience, we will need to fix, just not in the scope of this work. Will wait for your confirmation and can open issue.

MisRob · 2024-09-17T19:39:51Z

I'd like to ask

@radinamatic for QA (see Steps to Test) and read through on both documentation pages. Now it's time for detailed QA on KDS side - feel free to test keyboard and screen reader experience for all live examples on the pages.
@jtamiace @akolson @LianaHarris360 @AllanOXDi @AlexVelezLl @marcellamaki - would be grateful if you could read the two documentation pages
@AllanOXDi @AlexVelezLl - would you review code?

~~Note that even though the documentation build shows as failed in the PR checks, I was able to re-run it. Just use the links to the docs in the PR description.~~ Fixed

Thanks all :)

AllanOXDi · 2024-09-17T19:41:26Z

@AllanOXDi @AlexVelezLl - would you review code?
I will review it. Thanks

to prevent overwhelming visual otput.

MisRob · 2024-09-18T07:59:06Z

Thanks @AllanOXDi :)

For documentation pages code, I think there's no need to spend much time on it - it's large diff and if something went so wrong, we'd spot it on the generated docs. cc @AlexVelezLl

I think in one of the upcoming PRs, I'd like to move live examples to sub-components to make further updates of documentation simpler. Relatedly, I'd like to revive @AlexVelezLl's idea about toggling code. Perhaps something we can begin experimenting with and discuss as a potential pattern. Let's chat in meetings :)

AllanOXDi · 2024-09-19T14:42:52Z

Hi @MisRob I started reviewing this PR . Overall, the component is very robust and thoughtfully designed for flexibility and reusability. I have posted few comments for optimizations around code reuse, style handling, and event management. Thank you so much for your great work here.

AllanOXDi · 2024-09-19T15:05:27Z

lib/cards/KCard.vue

-       * Sets card title if provided. The title should be
-       * unique within a grid and descriptive to aid screenreader
-       * navigation.
+       * Card title
       */


Since title prop is set to null by default. We might want to add an additional check to ensure that either the title prop or the title slot is always present since this is critical for a for KCard .

AllanOXDi · 2024-09-19T15:16:18Z

lib/cards/KCard.vue

      },
      headingElement() {
        return this.headingLevel ? 'h' + this.headingLevel : undefined;
      },
-      layoutClass() {
-        return this.stylesAndClasses.layoutClass;
+      cardAreaClasses() {


To me it is appearing that there are minor redundancies in cardAreaClasses and thumbnailStyles. It might be worth refactoring these into helper functions to reduce code duplication, especially for the various combinations of orientation and thumbnail sizes?

AllanOXDi · 2024-09-19T15:53:03Z

lib/cards/KCardGrid.vue

+
+    setup(props) {
+      const { currentLevelConfig } = useResponsiveGridLayout(props);
+
+      const gridStyle = ref({});
+      const gridItemStyle = ref({});
+
+      watch(
+        currentLevelConfig,
+        newValue => {
+          const { cardsPerRow, columnGap, rowGap } = newValue;
+
+          gridStyle.value = {
+            'column-gap': columnGap,
+            'row-gap': rowGap,
+          };


It would be helpful to include more detailed comments here to make it easier for others like me

AllanOXDi · 2024-09-19T15:57:19Z

lib/cards/KCardGrid.vue

+    name: 'KCardGrid',
+
+    setup(props) {
+      const { currentLevelConfig } = useResponsiveGridLayout(props);


I think let's destructure props to make it clearer which properties are being used.

AllanOXDi · 2024-09-19T16:55:18Z

lib/cards/KCard.vue

@@ -150,19 +167,25 @@

  export default {
    name: 'KCard',
+    setup() {
+      // provided by `KCardGrid`


I think we change this comments to //gridItemStyle controls the width and layout of KCard items in the grid. either from here on KCardGrid

AllanOXDi · 2024-09-19T17:34:56Z

docs/pages/kcardgrid.vue

+
+      <p>Grid's visual behavior is based on the <DocsInternalLink text="window breakpoint system" href="/layout#responsiveness" />. <code>KCardGrid</code> determines how many cards per row to display based on its layout and a current window breakpoint.</p>
+
+      <p><code>KCardGrid</code> doesn't manage inner card content. This is <code>KCardGrid</code>'s responsibility.</p>


Contradictory Statement here. It might be clearer to state that KCardGrid does not manage the content but only the layout of the cards.

MisRob added 25 commits September 16, 2024 23:07

Move playground to a directory

bcb8bad

to have a suitable location for playground sub-components when testing complex scenarios

Add higher quality sample picture

9b95613

alongside the existing very small picture to allow for testing in both cases.

Add space below the belowTitle slot

406dcf9

to visually separate it from the footer slot.

Increase documentation content area size

ed26c35

to allow components that required more space to demonstrate their function in relevant ways, such as grids.

Fine-tune spacing and make it robust

9294705

Ensures spaces are rendered as expected no matter of whether some/all/none slots are displayed. Also aligns spaces more closely to designs.

Fix unprecise calculation

1fa9648

and use constants to define thumbnail width so they can be later referenced instead of hardcoded values..

Hide the placeholder after the thumbnail image is loaded

ef31f68

Otherwise in some scenarios, such as when there is a large placeholder element and a small thumbnail image, some parts of the placeholder element may be visible behind the image after it has been successfully loaded.

Add KCardGrid with base layouts

1f3cbf6

Add new documentation components

4c6ccbe

Add new KCardGrid docs and improve KCard docs

4ea1fb2

Rename titleLines to titleMaxLines

f7b7031

to communicate its function more clearly

Rename layout to orientation

6ee11aa

to communicate its purpose. The card layout is rather a combination of its orientation and the thumbnail area configuration.

Use available constants

3c84ce1

Add support for selection controls

c528ae0

Remove uneccessary doc folders

0cb34f2

Fix component name

dd8163c

Fix bookmark button's purpose not being announced

ac8a309

by screenreaders and add some docs.

Move card components to one directory

52cd595

Reset playground

58b3adb

Overview and Guidelines sections writing improvements

c11966e

Allow the docs toggle button be displayed inline next to related text

cb1ca39

Usage sections writing improvements

bfcf923

Remove duplicate information of API documentation sections

ae80bab

This information, with more, is now documented in the main documentaton sections.

MisRob marked this pull request as ready for review September 17, 2024 19:15

MisRob requested review from radinamatic, akolson and marcellamaki September 17, 2024 19:16

MisRob requested review from LianaHarris360, AlexVelezLl and AllanOXDi September 17, 2024 19:16

MisRob requested a review from jtamiace September 17, 2024 19:39

MisRob mentioned this pull request Sep 17, 2024

Add new design pattern documentation page for cards #264

Open

Specify the direction of cards stretching in docs

de61587

MisRob force-pushed the k-card-grid-2 branch from 3ac4f99 to 7bb2e0f Compare September 18, 2024 06:59

MisRob added 2 commits September 18, 2024 09:04

Do not use links for API references on a same page

1e6fd25

to prevent overwhelming visual otput.

Condense related info to the same paragraph

abede1c

MisRob force-pushed the k-card-grid-2 branch from 7bb2e0f to abede1c Compare September 18, 2024 07:05

MisRob force-pushed the k-card-grid-2 branch from 0d5f150 to 7ea263a Compare September 18, 2024 08:05

More realistict cards sample and add more content variety

9bfb21f

MisRob force-pushed the k-card-grid-2 branch from 7ea263a to 9bfb21f Compare September 18, 2024 15:33

AllanOXDi reviewed Sep 19, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

KCardGrid part 2: Add KCardGrid with the base layouts + Add selection controls + Final documentation for KCard and KCardGrid + Few KCard bugfixes and improvements #785

KCardGrid part 2: Add KCardGrid with the base layouts + Add selection controls + Final documentation for KCard and KCardGrid + Few KCard bugfixes and improvements #785

MisRob commented Sep 17, 2024 •

edited

Loading

MisRob commented Sep 17, 2024

MisRob commented Sep 17, 2024 •

edited

Loading

AllanOXDi commented Sep 17, 2024

MisRob commented Sep 18, 2024

AllanOXDi commented Sep 19, 2024

AllanOXDi Sep 19, 2024

AllanOXDi Sep 19, 2024

AllanOXDi Sep 19, 2024

AllanOXDi Sep 19, 2024

AllanOXDi Sep 19, 2024

AllanOXDi Sep 19, 2024


		<p>Grid's visual behavior is based on the <DocsInternalLink text="window breakpoint system" href="/layout#responsiveness" />. <code>KCardGrid</code> determines how many cards per row to display based on its layout and a current window breakpoint.</p>

		<p><code>KCardGrid</code> doesn't manage inner card content. This is <code>KCardGrid</code>'s responsibility.</p>

KCardGrid part 2: Add KCardGrid with the base layouts + Add selection controls + Final documentation for KCard and KCardGrid + Few KCard bugfixes and improvements #785

Are you sure you want to change the base?

KCardGrid part 2: Add KCardGrid with the base layouts + Add selection controls + Final documentation for KCard and KCardGrid + Few KCard bugfixes and improvements #785

Conversation

MisRob commented Sep 17, 2024 • edited Loading

Description

KCard bugfixes, visual and public API updates

KCardGrid

Docs

References

Changelog

Steps to test

Testing checklist

Reviewer guidance

Comments

MisRob commented Sep 17, 2024

MisRob commented Sep 17, 2024 • edited Loading

AllanOXDi commented Sep 17, 2024

MisRob commented Sep 18, 2024

AllanOXDi commented Sep 19, 2024

AllanOXDi Sep 19, 2024

Choose a reason for hiding this comment

AllanOXDi Sep 19, 2024

Choose a reason for hiding this comment

AllanOXDi Sep 19, 2024

Choose a reason for hiding this comment

AllanOXDi Sep 19, 2024

Choose a reason for hiding this comment

AllanOXDi Sep 19, 2024

Choose a reason for hiding this comment

AllanOXDi Sep 19, 2024

Choose a reason for hiding this comment

MisRob commented Sep 17, 2024 •

edited

Loading

`KCard` bugfixes, visual and public API updates

`KCardGrid`

MisRob commented Sep 17, 2024 •

edited

Loading