Create `KTable` public interface specification

[MisRob]

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!