Create `KTable` public interface specification

[MisRob]

❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.

Summary

Create a specification for the KTables public interface that fits our current use cases; scales well to future use-cases; and is readable, simple, and flexible.

Background

In GSoC 2024, @BabyElias introduced a new component, KTable. The focus of GSoC project was a robust a11y and basic documentation of the main parts. This issue tracks a next big step in KTable work.

Output

A detailed written specification of KTable public interface, similar to KImg or KCard specification.

Guidance

(1) Research

• Current documentation
• Current two Kolibri use-cases
• Designs for future use-cases
• Previous discussions about the public interface
• Other design systems

See "References".

(2) Create draft specification

and discuss any questions, alternative approaches, and important decisions with the dev team.

(3) Share for feedback

with the dev team.

(4) Incorporate feedback

and open the final GitHub specification issue.

References

GSoC 2024 KTable work

• KTable component
• KTable documentation
• Client-sorting use-case in Kolibri
• Backend-sorting use-case in Kolibri

Discussions about the public interface

• https://github.com/learningequality/kolibri-design-system/issues/743
  • Comments section contain useful high-level direction
  • @bjester's proposal of KTableHead, KTableBody, ...
  • @AlexVelezLl's proposal of sort handler, ...
• https://github.com/learningequality/kolibri-design-system/pull/824
  • @BabyElias and @EshaanAgg's discussion about issues observed with defaultSort, disableDefaultSorting, ...
  • Also see related @EshaanAgg's proposal in the comments of this issue
• https://gist.github.com/indirectlylit/665ba47aaaddddc76380591fe93a281e
  • Sortable table proposal by @indirectlylit long before GSoC but contains ideas that may be handy

Future features

TODO @MisRob link designs

[EshaanAgg]

Proposal: Custom Sorting for KTable

Summary

Enhance the KTable component by introducing custom sorting capabilities. These enhancements make sorting more flexible, user-friendly, and extendable for diverse data handling scenarios.

---

Feature Details

Currently, the KTable component supports sorting by clicking on column headers. We already have the disableBuiltinSorting attribute to disable this feature, but how the data should be sorted when sortable and disableBuiltinSorting are both true is not defined. This proposal aims to address this issue by introducing a new prop, customSort, to allow users to define custom sorting logic.

• New Prop:

  • customSort (optional): A function to define custom sorting logic.

    • Accepts:
      • rows (array): Current rows of the table.
      • columnIndex (number): Index of the column to sort by. This is determined by which column header was clicked.
      • currentSortOrder (string): Current sorting order ('asc', 'desc' or null). This is the current sorting order of the column that was clicked. It is equal to null if the column was not sorted before, or the sorting had been performed on some other column (AKA sortKey).
    • Returns an object:
      • rows (array): Sorted rows.
      • sortOrder (string): New sorting order ('asc', 'desc', null).
      • sortKey (number): Index of the column which should be marked as sortKey.

    Using the return object, the KTable component will update the rows and all the headers of the table accordingly.

I propose to add the same alongside the existing changeSort event emission, as now the developer would have the choice of whether he/she just wants to track the sorting requests from the user (via the event) or wants to handle the sorting logic themselves (via the customSort prop).

• Usage Example:

  customSort(rows, columnIndex, currentSortOrder) {
    console.log(`Custom sorting logic for column index: ${columnIndex}`);
    // Demo Implementation: Reverse the rows and toggle the sorting order
    const newRows = rows.reverse();
    return {
      rows: newRows,
      sortOrder: currentSortOrder === 'asc' ? 'desc' : 'asc',
      sortKey: columnIndex,
    };
  }
  

  <KTable
    sortable
    disableBuiltinSorting
    :headers="headers"
    :rows="rows"
    :customSort="customSort"
  />
  

[MisRob]

Thanks a lot @EshaanAgg!

[lokesh-sagi125]

Hey @MisRob, I would love to create the public interface specification for @BabyElias 's work. Can I get started on this?

[MisRob]

Hi @lokesh-sagi125, I appreciate your offer. Generally speaking, at this point it's not open for contribution. We may consider turning it into a GSOC project or offer as a large project to senior contributors with whom we have worked very closely for a long time, however that wouldn't be sooner than second quarter of 2025.

I'd recommend to focus on 'help wanted'. I know there aren't many right now as we're slowly approaching the end of year when LE will be closed for two weeks. I think there will be more new issues in the second half of January. If you'd like to work on something more complex, and rather sooner, there's one experimental issue I opened https://github.com/learningequality/kolibri-design-system/issues/691. However note this would be really about research and proof of concept - if we find out it's not feasible, we may decide to not move in this direction. Still, I see value in it and would appreciate if someone looked at it quite independently. Depending on your goals, you should know it may not be the most rewarding task :) Also note that likely I'd be the contact person for this one, and won't be available until January 13, 2025.

[lokesh-sagi125]

sure, @MisRob, I am more than happy to work on other issues :)