Resource discovery: Implement folder and resource card

[AllanOXDi]

Summary

The PR introduces a new folder card to Kolibri to support of coach resource discovery . See #12318

Screen.Recording.2024-07-25.at.19.53.42.mov

closes #12318

References

#12318

Reviewer guidance

While reviewing this PR, please note that I have decided to leave out a few acceptance criteria requirements, namely support for RTL.

Please note that this was built on top of the KCard, which supports two layouts (i.e., vertical and horizontal) with their respective thumbnail display options and for folder cards, the thumbnail display area is currently shown on the left when the display is large. but it require it to be on the right when the thumbnailDisplay prop is set to 'large', in addition to the title prop taking up the position of the above title slot in these kinds of layouts. This is currently not covered by KCard.

Vs the design spec

After discussing with @MisRob, we decided to work with what KCard supports for this issue and file a follow-up issue on KDS to handle these edge cases.

I have made a minor stying adjustment to the below title slot on KCard . To test this PR you would need to work with this KDS PR learningequality/kolibri-design-system#688

Here are a few things to look at:

• Does it have Folder titleF, icon , label and Folder thumbnail picture?
• Folder thumbnail placeholder when a picture is not available?
• Is it responsive ?

Testing checklist

• Contributor has fully tested the PR manually
• If there are any front-end changes, before/after screenshots are included
• Critical user journeys are covered by Gherkin stories
• Critical and brittle code paths are covered by unit tests

PR process

• PR has the correct target branch and milestone
• PR has 'needs review' or 'work-in-progress' label
• If PR is ready for review, a reviewer has been added. (Don't use 'Assignees')
• If this is an important user-facing change, PR or related issue has a 'changelog' label
• If this includes an internal dependency change, a link to the diff is provided

Reviewer checklist

• Automated test coverage is satisfactory
• PR is fully functional
• PR has been tested for accessibility regressions
• External dependency files were updated if necessary (yarn and pip)
• Documentation is updated
• Contributor is in AUTHORS.md

[github-actions]

Build Artifacts

Asset type	Download link
PEX file	kolibri-0.18.0.dev0_git.20240924172741.pex
Windows Installer (EXE)	kolibri-0.18.0.dev0+git.20240924172741-windows-setup-unsigned.exe
Debian Package	kolibri_0.18.0.dev0+git.20240924172741-0ubuntu1_all.deb
Mac Installer (DMG)	kolibri-0.18.0.dev0+git.20240924172741.dmg
Android Package (APK)	kolibri-0.18.0.dev0+git.20240924172741-0.1.4-debug.apk
TAR file	kolibri-0.18.0.dev0+git.20240924172741.tar.gz
WHL file	kolibri-0.18.0.dev0+git.20240924172741-py2.py3-none-any.whl

[MisRob]

Hi Allan, thanks :) I appreciate clarity in the PR description in regard to review and also what's done and what's coming, helpful. I hope to have all issues I promised to open ready soon. Cards look very good, and their API interface makes sense to me. I am leaving a couple of comments from the first code walkthrough.

[MisRob]

Not so important as it's temporary change, rather just fyi for future work there's constants available here

kolibri/kolibri/core/assets/src/constants.js

Lines 28 to 42 in df0c4ee

	export const ContentNodeKinds = {
	AUDIO: 'audio',
	DOCUMENT: 'document',
	VIDEO: 'video',
	EXERCISE: 'exercise',
	TOPIC: 'topic',
	HTML5: 'html5',
	CHANNEL: 'channel', // e.g. a root topic
	EXAM: 'exam',
	LESSON: 'lesson',
	CLASSROOM: 'CLASSROOM',
	ACTIVITY: 'ACTIVITY',
	SLIDESHOW: 'slideshow',
	BOOKMARK: 'bookmark',
	};

[MisRob]

[required] I'd suggest that <AccessibleFolderCard> has a headingLevel prop and just passes its value to KCard via the same prop. Reason being that <AccessibleFolderCard> will be used from more pages in Kolibri, and on each page it can be a member of a different level. This will ensure that devs always make sure to configure it explicitly and correctly in the context of a given page.

[MisRob]

[required] Regarding the usage of <CardThumbnail> here, KCard doesn't need to use another component to re-implement the whole thumbnail area because it already provides it. If we used <CardThumbnail> here, that would override everything in unintended ways, and it's also unnecessary extra work. Let's leave KCard to do everything it can and only put folder icon into the #thumbnailPlaceholder slot. I realize that the slot's name is not intuitive in this regard - can you think of a better name?

(side note for context, ultimately, a big future goal is to get rid of all current card components in Kolibri, <CardThumbnail> included, in favor of KCard)

[AlexVelezLl]

Thank you @AllanOXDi! Its super exciting to see KCard already being used in our codebase!! 🎉, and see that the initial implementation has covered the most usecases we had. I left just a couple of thoughts, mostly regarding the html semantic structure 🤗.

[marcellamaki]

Hi @AllanOXDi thanks for the great work on this!

My main suggestion here is for this PR but also helps us with the "how do we move past a working branch into the 'mainline' work for 0.18 question".

We should move both the ResourceCard and the FolderCard to kolibri-common. This allows the work to be merged into develop with minimal additional changes, provides the cards for shared use, and also prevents cross-plugin imports (totally fine for this working branch and testing, but not something we want to merge into production. Why no cross-plugin imports? Since it's a plugin architecture, we cannot merge code that assumes the existence of another plugin. Each plugin shouldn't "know" about other plugins that exist, or depend on them. More questions? Richard would love to tell you about it).

Having this implementation as it is, and using the updated version in the content card list is very helpful for manual QA. So, after moving these new components into kolibri-common, please update the reference for the import in the ContentCardList for final QA and feedback, so we can make sure everything moved over well.

Once all of the feedback on the cards themselves is resolved, and we confirm with QA that the new cards work as expected in Coach in the ContentCardList with no regressions, I think we can retarget this PR to develop and merge it directly there. I will then update the related issues in the milestone to be follow up issues that build on top of this foundation. I'm going to think about whether or not we want to include the ContentCardList update, or if we just want to include the cards being available in kolibri-common with no actual "placement" of them yet. If anyone has pros/cons, please share.

Also, a bit of a nitpick, but let's have a consistent name for the new cards -- I think making sure it's Accessible_____Card for each makes sense, so update AccessibilityResourceCard to be AccessibleResourceCard.

Great work! I'm so excited that finally KCard in Kolibri is coming to life!!!! 🎉 🎉 🎉 🎉 🎉 It's been a long time coming, and past Marcella, who struggled through 0.15 card refactoring (and many patch release "fixes" on the card UI ever since), is very grateful!

[MisRob]

@AllanOXDi After all feedback here is resolved, and also learningequality/kolibri-design-system#752 finished and linked here, please ping me here - will do one final read through and then we should be ready to develop merge.

[marcellamaki]

Hi @MisRob @AllanOXDi - I have started my review here and have a few thoughts. I'll add some comments and questions tomorrow. Some of them are probably for follow up and some are more general questions as I get more familiar with the relationships between these cards and KCard. Overall it's looking really nice Allan, thanks for all of your hard work!

[marcellamaki]

Hi @AllanOXDi Thank you for the great work on this. I can really see your increased comfort with all thing Vue components and navigating between KDS components and custom components in our products! I added a couple of comments but they're small.

Aside from the comments, I wanted to raise a little feedback that is outside of the scope of this PR but is interesting for the sake of learning and planning around the mobile view of the cards and this project.

On mobile view of the Folder card, the layout is technically responsive, which is great, but you can see it's a bit crowded.

I realize that the screenshot included in the issue only had more of a "list" view and didn't clearly state that there would be different sizes on mobile. And the image preview in the issue didn't include the mobile level responsiveness specifically. When we actually use this card (beyond just what you have here for the demo), I think we'll want to make sure we use the version of KCard that is aligned with the spec..

From my understanding talking to @MisRob, it will be simple to do this with a different layout that exists, to be vertical vs. horizontal, which is already supported in KCard

You could try out doing this conditionally where the card is called

  <Accessible...Card layout=breakpointLevel === 0 ? "'vertical" : "'horizontal">

but only if you're curious to test it out and see for yourself, as this isn't the final usage and you will be removing that code before merge anyways :)

In upcoming work I'd also encourage you to use a critical/reflective eye when are playing around with testing, and raise questions like "does this look right? did we overlook a mobile display? does this seem like what the designer intended?" Again, this isn't strictly in scope for this PR as the current "use" of the card is for manual QA only. And it's not a criticism of the implementation, but rather some thoughts to help with broader context thinking beyond the checklist of acceptance criteria. Noticing and sharing your perspective on things early, even if it seems like something a bit outside of your task list, is always helpful, and it helps you continue to build those reflective/questioning skills 🙂 And practically speaking, it will also help us make sure we do things like share with the team some of these features of the new KCard and helps me remember to include these details in upcoming issues I'm writing.

[marcellamaki]

I'm wondering why there's a need to use /deep/ here, and if this is because this is more of an MVP, rather than the full implementation, or if there's something that we're missing with the KCard API. To me this is a small thing but an indicator that something is not quite as flexible as it needs to be, or like we've missed a detail and now are overriding something where there might be a better approach.

This is a bit of a nitpick, but I'm also confused about why the height is 141 px specifically. Was it this in the spec? We usually stick with 4 or 8px increments, or at the very least an even number.

[AllanOXDi]

currently, KCard has no set hight and and width- it's something that will be implemented in the gird. So I was just trying to play around with the number to make sure I'm close tot the the design

[MisRob]

I asked @AllanOXDi to not worry too much about these temporary files :) As mentioned this won't be configured on KCard at all and this whole file will be removed before we merge.

However, it's definitely relevant notes and good guidance. @AllanOXDi it may be be helpful to comment on things like this in the PR comments or code comments so reviewers who don't have context (or just people like me with bad memory :-) can understand things like this.

[marcellamaki]

Let's just make sure to remove this before merge

[AllanOXDi]

Okay. Once It's approve, I will remove it before merge. I wish I had added a comment

comments addressed

[marcellamaki]

@AllanOXDi I think the last thing here is just to clean up any code that was used only for QA, and then we can go ahead and merge! Thank you for all the hard work managing this in connection with the KCard updates

[AllanOXDi]

Okay thanks @marcellamaki. @MisRob is there something still missing?

[MisRob]

@AllanOXDi I will give it a final look after QA related code is cleaned up

[MisRob]

@AllanOXDi I'm sorry there's still some changes that shouldn't be here before merge. Would you always preview "Files changed" tab? I'm not particularly concerned about added/removed empty lines etc. but for example the extra condition in the ContentCardList would cause the current cards to not be present at all. I'd also ask you to double-check other files.

[AllanOXDi]

The v-else? have removed it

[MisRob]

I don't think you pushed it then @AllanOXDi or perhaps internet connection troubles? See here https://github.com/learningequality/kolibri/pull/12418/files
. It's really best to preview "Files changed" because than you can exactly what others see.

[AllanOXDi]

Sorry I think It should be okay now.

[MisRob]

Thanks @AllanOXDi

[MisRob]

Please clean up the last two places I spotted and then you can merge.

[MisRob]

Not that it'd be wrong in the scope of this PR - it will just make work easier for those to come because it'd break the grid behavior unexpectedly otherwise. Thanks

[MisRob]

Okay, nice. I think as soon as checks pass, this is ready. Thanks for following-up @AllanOXDi, I will leave joy of hitting the merge button for you ;)