From f208c0c00bfe465127cc360f4503af2672849bc6 Mon Sep 17 00:00:00 2001 From: Stephen Watkins Date: Tue, 15 Aug 2023 14:32:10 -0400 Subject: [PATCH] initial spec --- documentation/specs/DisplayTable.md | 209 +++++++++++++++++++++++++++- 1 file changed, 203 insertions(+), 6 deletions(-) diff --git a/documentation/specs/DisplayTable.md b/documentation/specs/DisplayTable.md index 36359f2c..3166bd4e 100644 --- a/documentation/specs/DisplayTable.md +++ b/documentation/specs/DisplayTable.md @@ -8,24 +8,221 @@ A `DisplayTable` is used for presenting information displayed across columns and ## Design -`DisplayTable` is only for presentational concerns. It doesn't support advanced capabilities such as selection, sorting, and row expansion. With that in mind, complexities are primarily shifted to surfacing a simple component API, structuring the table properly to support the style requirements, and ensuring that accessibility markup is applied correctly. +`DisplayTable` is for presentational concerns only. It doesn't support interaction such as selection, sorting, and row expansion. For an interactive table accommodating advanced use cases, see `Table`. -Even though `DisplayTable` doesn't do much in terms of functionality, because accessibility concerns can be non-trivial, we will use `useTable` from React Aria to ensure that we have our accessibility bases covered. +Without interaction, complexities are shifted to surfacing a simple component API, structuring the table for style requirements, and ensuring appropriate application of accessibility markup. + +`DisplayTable` will use React Aria's `useTable` under the hood to reliably generate accessibility markup for the table. ### API ```ts +type DisplayTableProps = AriaLabelingProps & { + /** Columns for the table. */ + columns: Column[]; + + /** + * Horizontal alignment of data within their cells. + * @default start + */ + dataAlignment?: "start" | "center" | "end"; + + /** Renders the first row cell as a row header. */ + hasRowHeaders?: boolean; + + /** Rows for the table. */ + rows: Row[]; +}; + +type Row = Cell[]; + +type Cell = + | ReactNode + | { + /** Cell text. */ + text?: ReactNode; + + /** Cell icon. */ + symbol?: IconSymbol; + /** Mark cell as highlighted. */ + isHighlighted?: boolean; + }; + +type Column = + | ReactNode + | { + /** Column heading. */ + heading?: ReactNode; + + /** Column subheading. */ + subheading?: ReactNode; + + /** Column heading icon or image. */ + media?: ImgMedia | IconMedia; + }; + +type IconMedia = { + symbol: IconSymbol; +}; + +type ImgMedia = { + src: string; + alt: string; +}; ``` ### Example Usage -_Simple_: +_Basic usage_: ```tsx -import { Modal } from "@easypost/easy-ui/Modal"; +import { DisplayTable } from "@easypost/easy-ui/DisplayTable"; -function PageWithModal() { - return ; +function CustomDisplayTable() { + return ( + + ); } ``` + +_Advanced usage_: + +```tsx +import { DisplayTable } from "@easypost/easy-ui/DisplayTable"; + +function CustomDisplayTable() { + return ( + + ); +} +``` + +--- + +## Behavior + +### Accessibility + +Tables are used to organize data with a logical relationship in grids. Accessible tables need HTML markup that indicates header cells and data cells and defines their relationship. Assistive technologies use this information to provide context to users. + +- Tables must have a thead, containing a th for each column. +- Tables must have a tbody wrapping the table body of rows. +- Tables should include row headers as the first cell in a row. +- `DisplayTable` should contain static textual and numeric data rather than actionable components. For more advanced cases, see `Table`. + +Most accessibility concerns will be handled through React Aria. + +## Dependencies + +- `react-aria`—`useTable` +- `@easypost/easy-ui`—`useIntersectionDetection` for the stuck styles