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

[MisRob]

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

• Description: Renames KCard's titleLines prop to titleMaxLines

• Products impact: updated API

• Addresses: -

• Components: KCard

• Breaking: yes

• Impacts a11y: no

• Guidance: Rename the prop

• Description: Renames KCard's layout prop to orientation

• Products impact: updated API

• Addresses: -

• Components: KCard

• Breaking: yes

• Impacts a11y: no

• Guidance: Rename the prop

• Description: Adds support to KCard for selection controls such as checkboxes

• Products impact: new API

• Addresses: -

• Components: KCard

• Breaking: no

• Impacts a11y: yes

• Guidance: -

• Description: Improves spaces display in KCard

• Products impact: visual update

• Addresses: -

• Components: KCard

• Breaking: no

• Impacts a11y: no

• Guidance: -

• Description: Hides KCard placeholder element after the thumbnail image is loaded

• Products impact: bugfix

• Addresses: Resolves issue when parts of the placeholder element was visible behind a small thumbnail image

• Components: KCard

• Breaking: no

• Impacts a11y: no

• Guidance: -

• Description: Updates KCard to make screen readers announce only card titles when navigating the grid with TAB key

• Products impact: bugfix

• Addresses: Resolves unexpected behavior when overwhelming amounts of information was announced when navigating the card list with TAB

• Components: KCard

• Breaking: no

• Impacts a11y: no

• Guidance: -

• Description: Introduces KCardGrid (with internal related KCard updates)

• Products impact: new API

• Addresses: KCardGrid MVP and specification #697, KCard: Allow the height of sections to be configured and related improvements #703

• Components: KCardGrid

• Breaking: no

• Impacts a11y: no

• Guidance: -

• Description: Adds detailed guidance to KCard and KCardGrid documentation pages

• Products impact: none

• Addresses: Add new design pattern documentation page for cards #264, Add more guidance to KCard docs #696

• Components: KCard, KCardGrid

• Breaking: no

• Impacts a11y: no

• Guidance: -

• Description: Adds new documentation components: DocsSubNav, DocsToggleButton, DocsToggleContent, DocsTable

• Products impact: none

• Addresses: Helps with organizing larger amounts of guidance on documentation pages

• Components: -

• Breaking: no

• Impacts a11y: no

• Guidance: -

• Description: Slightly increases the width of the main documentation area

• Products impact: none

• Addresses: Helps to better demonstrate components requiring more space on documentation pages, such as card grids

• Components: -

• Breaking: no

• Impacts a11y: no

• Guidance: -

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

[MisRob]

Thanks a lot @AllanOXDi. I pushed some updates and left couple of clarifying questions.

[AlexVelezLl]

Thank you @MisRob!! This is looking great!! Loved how KCard and KCardGrid docs are structured, and code changes looks good to me. I left just a couple of questions/concerns, that Im not sure if falls in the scope of this PR. Thanks!

[LianaHarris360]

I've read over the documentation a bit and only noticed a few things:

1. There's a typo in this sentence

2. When you click on a card within the documentation, you see an error message saying "This page could not be found." Could we make it so that the card is still clickable, but clicking it just keeps the user on the same page (or takes the user nowhere or perhaps to the top of that section) instead of opening that page?

[radinamatic]

Excellent work @MisRob , I'm so 😍 with the progress here! 👏🏽 🏅 💯

Even though some further attention will be necessary for proper labeling of the interactive elements within the card, this is a very strong and accessible foundation! Keyboard navigation is fluid, without hickups, and with the order we agreed upon, screen reader output is according to the expectations! 🎉

Bookmark	Checkbox

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.

According to the W3C ARIA Authoring Practices Guide, the expected checkbox pattern requires only the Space key to change the state from checked to unchecked and back, so we should be good 🙂

[radinamatic]

Accessibility-wise, this is ready to 🚀! 🙂 🎉

[marcellamaki]

@MisRob - I have read through the documentation and find it comprehensive and well-organized. There may be things that we end up wanting to add or adjust as we start implementing (and I think it would be ideal if some of the engineers who are less familiar with this do some of the refactoring work in 0.18, so we can get a new perspective on the work and documentation and see what additional information is useful for the team. (I haven't done any code review, as it seems as though that's been covered by others, and that Radina has done comprehensive accessibility QA as well)

[MisRob]

@LianaHarris360 Thank you.

(1) Fixed
(2) Yes, that'd be nice. I redirected to the "Guidelines" section so we can still easily recognize navigation works.

[MisRob]

Good news @radinamatic, thank you

[MisRob]

Thanks for reading through it @marcellamaki. Yes, it'd be great if cards could be now used by more developers who would give feedback.

[MisRob]

All actionable feedback addressed. I am going to update changelog and open 'beta' -> 'this final version' migration issues for existing Kolibri and Studio cards and then we can merge.