Skip to content

Commit

Permalink
[WIP] Add useKCardGrid for customization of KCardGrid
Browse files Browse the repository at this point in the history 
and related updates:

- Adds private 'useGridConfig' to store configurations
  for all grids so they can be later updated via
  use KCardGrid. Furthemore, it observes window size
  and returns the final grid configuration to 'KCardGrid'
  for the current breakpoint
- Removes 'useResponsiveGridLayout' in favor of 'useGridConfig'
- Consistent language around breakpoints and simplifies
  'gridBaseLayouts'
  • Loading branch information
@MisRob
MisRob committed Sep 19, 2024
1 parent c0e536d commit 7198a9f
Show file tree
Hide file tree
Showing 7 changed files with 221 additions and 135 deletions.
40 changes: 32 additions & 8 deletions docs/pages/kcard.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@
<p>It manages the layout, including the thumbnail image, title, and other content. It offers several base layouts and many customization options. Cards like the examples shown can be created, and many others.</p>

<DocsShow block :style="{ maxWidth: '800px' }">
<KCardGrid layout="1-1-1">
<KCardGrid
gridId="grid-1"
layout="1-1-1"
>
<DocsKCard
:headingLevel="3"
:orientation="windowBreakpoint > 2 ? 'horizontal' : 'vertical'"
Expand Down Expand Up @@ -243,7 +246,10 @@
<p><code>KCard</code> has two orientations: horizontal and vertical. It is also possible to configure whether a thumbnail area is displayed, its size and alignment. By combining <code>orientation</code>, <code>thumbnailDisplay</code> and <code>thumbnailAlign</code> props, the following card layouts can be achieved to organize diverse kinds of content:</p>

<DocsShow block>
<KCardGrid layout="1-2-3">
<KCardGrid
gridId="grid-2"
layout="1-2-3"
>
<DocsKCard
:headingLevel="4"
orientation="vertical"
Expand Down Expand Up @@ -303,7 +309,10 @@
</DocsShow>

<DocsShow block>
<KCardGrid layout="1-2-2">
<KCardGrid
gridId="grid-3"
layout="1-2-2"
>
<DocsKCard
:headingLevel="4"
orientation="horizontal"
Expand All @@ -324,7 +333,10 @@
</DocsShow>

<DocsShow block>
<KCardGrid layout="1-2-3">
<KCardGrid
gridId="grid-4"
layout="1-2-3"
>
<DocsKCard
:headingLevel="4"
orientation="vertical"
Expand Down Expand Up @@ -413,7 +425,10 @@
<p>Use <code>aboveTitle</code>, <code>belowTitle</code>, and <code>footer</code> slots to add content to a card. <code>KCard</code> will organize these areas according to its <DocsInternalLink text="layout configuration" href="#layout" />. Apply custom styling to the inner content of slots to achieve desired effects.</p>

<DocsShow block>
<KCardGrid layout="1-1-1">
<KCardGrid
gridId="grid-5"
layout="1-1-1"
>
<KCard
:to="{ path: '/test-url' }"
:headingLevel="4"
Expand Down Expand Up @@ -497,7 +512,10 @@
<p>Use the <code>thumbnailPlaceholder</code> slot to add a placeholder element, such as an icon, to this area. <em>Provide a placeholder element even if a thumbnail image is available.</em> This serves as a progressive loading experience where the placeholder element is displayed until the image is loaded, and is particularly important on slower networks.</p>

<DocsShow block>
<KCardGrid layout="1-1-1">
<KCardGrid
gridId="grid-6"
layout="1-1-1"
>
<DocsKCard
:headingLevel="4"
:orientation="windowBreakpoint > 2 ? 'horizontal' : 'vertical'"
Expand Down Expand Up @@ -546,7 +564,10 @@
<p><em>This applies to all slot content, but considering accessibility is especially important with interactive elements.</em> For instance, <code>ariaLabel</code> is applied to the bookmark icon button in the following example so that screenreaders can communicate its purpose. In production, more work would be needed to indicate the bookmark's toggled state. Always assess on a case-by-case basis.</p>

<DocsShow block>
<KCardGrid layout="1-1-1">
<KCardGrid
gridId="grid-7"
layout="1-1-1"
>
<DocsKCard
:headingLevel="4"
:orientation="windowBreakpoint > 2 ? 'horizontal' : 'vertical'"
Expand Down Expand Up @@ -594,7 +615,10 @@
<p>Managing the selection state is not <code>KCard</code>'s responsibility.</p>

<DocsShow block :style="{ maxWidth: '800px' }">
<KCardGrid layout="1-1-1">
<KCardGrid
gridId="grid-8"
layout="1-1-1"
>
<DocsKCard
:to="{ path: '/kcard' }"
:headingLevel="4"
Expand Down
30 changes: 24 additions & 6 deletions docs/pages/kcardgrid.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,10 @@
</DocsToggleContent>

<DocsShow block>
<KCardGrid layout="1-1-1">
<KCardGrid
gridId="grid-1"
layout="1-1-1"
>
<DocsKCard
v-for="i in 2"
:key="i"
Expand Down Expand Up @@ -141,7 +144,10 @@
</DocsToggleContent>

<DocsShow block>
<KCardGrid layout="1-2-2">
<KCardGrid
gridId="grid-2"
layout="1-2-2"
>
<DocsKCard
v-for="i in 3"
:key="i"
Expand Down Expand Up @@ -196,7 +202,10 @@
</DocsToggleContent>

<DocsShow block>
<KCardGrid layout="1-2-3">
<KCardGrid
gridId="grid-3"
layout="1-2-3"
>
<DocsKCard
v-for="i in 5"
:key="i"
Expand Down Expand Up @@ -234,7 +243,10 @@
<p><em>Setting height on cards is discouraged. Instead, manage height bottom-up, for example by setting height on card sections, using text truncation, or other ways to limit its inner content.</em> Such approaches ensure content tolerance, prevent from unexpected overflows or excessive height, and keep vertical alignment of card sections consistent on a grid row. This is especially important when dealing with unknown lenghts or amounts of content displayed in cards. Consider:</p>

<DocsShow>
<KCardGrid layout="1-2-3">
<KCardGrid
gridId="grid-4"
layout="1-2-3"
>
<DocsKCard
:headingLevel="4"
preserveAboveTitle
Expand Down Expand Up @@ -402,7 +414,10 @@
<p>Grid configuration can be combined with <code>KCard</code>'s settings to further improve responsive experience. A common pattern is switching <code>KCard</code>'s horizontal orientation to vertical for smaller screens to organize content more effectively in limited space:</p>

<DocsShow block>
<KCardGrid layout="1-2-2">
<KCardGrid
gridId="grid-4"
layout="1-2-2"
>
<DocsKCard
v-for="i in 2"
:key="i"
Expand Down Expand Up @@ -441,7 +456,10 @@
<p>This technique also works for adjusting <code>KCard</code> slots content. In the following example, some metadata pills are hidden on smaller screens:</p>

<DocsShow block>
<KCardGrid layout="1-2-2">
<KCardGrid
gridId="grid-5"
layout="1-2-2"
>
<DocsKCard
v-for="i in 2"
:key="i"
Expand Down
21 changes: 17 additions & 4 deletions lib/cards/KCardGrid.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
import { watch, ref, provide } from '@vue/composition-api';
import { LAYOUT_1_1_1, LAYOUT_1_2_2, LAYOUT_1_2_3 } from './gridBaseLayouts';
import useResponsiveGridLayout from './useResponsiveGridLayout';
import useGridConfig from './useGridConfig';
/**
* Displays a grid of cards `KCard`.
Expand All @@ -30,14 +30,17 @@
name: 'KCardGrid',
setup(props) {
const { currentLevelConfig } = useResponsiveGridLayout(props);
const { currentBreakpointConfig } = useGridConfig(props);
const gridStyle = ref({});
const gridItemStyle = ref({});
watch(
currentLevelConfig,
currentBreakpointConfig,
newValue => {
if (!newValue) {
return;
}
const { cardsPerRow, columnGap, rowGap } = newValue;
gridStyle.value = {
Expand All @@ -62,6 +65,16 @@
};
},
props: {
/**
* The id of the grid unique to a page
*/
// used from 'useGridConfig'
/* eslint-disable-next-line kolibri/vue-no-unused-properties */
gridId: {
type: String,
required: true,
},
/* eslint-enable-next-line kolibri/vue-no-unused-properties */
/**
* Sets the base grid layout.
*
Expand All @@ -78,7 +91,7 @@
*/
// eslint-disable-next-line kolibri/vue-no-unused-properties
layout: {
required: false,
required: true,
type: String,
default: '1-2-2',
validator: value => {
Expand Down
Loading

0 comments on commit 7198a9f

Please sign in to comment.