docs(Table): write documentation and guidelines (#2286)

resolves #1343
resolves #2281

---------

Co-authored-by: Michael Marszalek <[email protected]>

packages/react/src/components/Table/Table.mdx

@@ -8,27 +8,163 @@ import { TableHeaderCell } from './';
 
 # Table
 
+Table kalles tabell på norsk. Tabeller gjør det enklere for brukerne å skanne og sammenligne informasjon.   
+
 <Primary />
 <Controls />
 
-# Sortering
+## Slik bruker vi table
 
-`TableHeaderCell` har ein `sortable` prop som kan brukast for å visa at rada er sortberbar.
-Du sender inn `sort` prop til `TableHeaderCell` for å indikere at rada er sortert på den.
-Bruk `onSortClick` prop for å handtere klikk på sorterbare rader.
+```jsx
+import { Table } from '@digdir/designsystemet-react';
 
-<Canvas of={TableStories.Sortable} />
+<Table>
+  <Table.Head>
+    <Table.Row>
+      <Table.HeaderCell>
+        Header 1
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Header 2
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+        Cell 1
+      </Table.Cell>
+      <Table.Cell>
+        Cell 2
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+```
+
+## Tabelltekster
+
+Bruk [`caption`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption) til å beskrive en tabell 
+på samme måte som vi ville brukt en overskrift.
+En tabelltekst hjelper brukerne til å finne, navigere og forstå tabeller.
+Denne plasseres rett etter `Table`-taggen.
+
+```jsx
+<Table >
+  <caption>Her er tittelen på tabellen</caption>
+  ...
+</Table>
+```
+
+## Tabelloverskrifter
+
+Bruk tabelloverskrifter til å fortelle brukerne hva som er innholdet i radene og kolonnene. 
+Bruk [scope-atributtet](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#scope) til å hjelpe brukere av hjelpeteknologi til å 
+skille mellom overskriftene på rader og kolonner.  
+
+## Tall i en tabell
+
+Når det er tall i en tabell som skal sammenlignes, plasser tallene til høyre i tabellfeltet.
+
+## Varianter av table
 
-# Sticky header
+Tabeller kan være enkle med få rader og kolonner, eller de kan ha mye innhold med interaktive komponenter som lenker, knapper, 
+avkryssingsbokser og nedtrekkslister. 
+
+Alle tabeller har titler på kolonner og mulighet for å sortere dataene i kolonnen. 
+Tabellen skal kunne vises i den bredden som innholdet krever.   
+
+### Sticky header
+
+Bruk `stickyHeader={true}` for å få en sticky header.
 
 <Canvas of={TableStories.StickyHeader} />
 
-# Med form elementer
+### Med form elementer
 
-Du kan legge inn form elementer i ein tabell, men du må håndtere logikken sjølv.
+Du kan legge inn form elementer i ein tabell, men du må håndtere logikken selv.
 
 <Canvas of={TableStories.WithFormElements} />
 
+### Sortering
+
+`TableHeaderCell` har en `sortable` prop som kan brukes for å visa at raden er sortberbar.
+Bruk `sort` prop på `TableHeaderCell` for å indikere rekkefølgen radene er sortert.
+Bruk `onSortClick` prop for å håndtere klikk på sorterbare rader.
+
+<Canvas of={TableStories.Sortable} />
+
+### Fixed
+
+Du kan legge på `table-layout: fixed` for å få en tabell som ikke endrer bredden på kolonnene når innholdet endrer seg.
+Dette hjelper nettleseren til å tegne tabellen raskere, og er nyttig når du har paginering eller andre elementer som endrer innholdet i tabellen.
+
+<Canvas of={TableStories.FixedTable} />
+
+## Retningslinjer for når du skal bruke table
+
+Vi bruker `Table` når vi skal organisere og vise data på en strukturert måte i rader og kolonner for brukerne.  
+Alt innhold bør være venstrejustert i tabeller, unntatt tall som bør høyrejusteres for at brukerne lett skal kunne sammenligne tallene.  
+For å spare plass, kan vi bruke en meny, hvis flere handlinger i en tabellrad ikke må være synlig for brukerne hele tiden. 
+I overskiftceller bruker vi `<Table.HeaderCell>`, ikke `<Table.Cell>`. En celle er en overskrift hvis den beskriver 
+innholdet i cellene under eller ved siden av.
+
+Passer til å
+- gjøre det enkelt for brukerne å sammenligne og skanne informasjon
+- organisere og vise data på en effektiv måte i rekker og kolonner
+
+Passer ikke til å 
+- lage layout for innholdet på nettsiden eller å dele opp innholdet på en side systematisk
+- vise store mengder data på mobil
+
+## Tekst i komponenten
+
+Vi bruker overskrifter til å fortelle brukerne hva som er innholdet i radene og kolonnene.
+
+Innholdet i cellene skal som regel være venstrejustert.
+Unntak som skal være høyrejustert:
+- Tall og valuta
+- Knapper
+
+<br />
+
+For å gjøre tabellraden lesbar på smale skjermer, skal innholdet normalt være toppjustert.
+Men hvis raden har en eller flere knapper, bruker vi sentrering.
+Overskrifter kan med fordel gjøres `sticky`, det vil si at de fortsatt blir vist, selv om brukeren ruller nedover i tabellen. 
+
+## Tilgjengelighet
+
+Selv om ulike skjermlesere håndterer tabeller litt forskjellig, har de til felles at bare en liten del
+av tabellen kan presenteres om gangen, ofte bare én celle.
+Tabellceller bør ikke slås sammen, og cellene bør kun inneholde ett interaktivt element. Da får brukerne 
+raskt oversikt over innholdet og kan sammenligne og scanne informasjonen.
+
+Alle tabeller må ha overskrifter for hver kolonne (`<Table.HeaderCell>`). Unntaket er kolonner som inneholder kun har 
+interaktive elementer, de skal ha ledetekst. Se eksempel ["Med form elementer"](#med-form-elementer).
+
+For at brukerne skal kunne navigere i innholdet med skjermleser, må det være overskrifter i kolonnene.
+Hvis det er behov for å spare plass, kan vi visuelt skjule en eller flere overskrifter.
+
+Det kan være vanskelig å vise tabeller på mobil, siden det ikke finnes et felles design som fungerer i alle sammenhenger.
+Noen ganger er det nødvendig å sammenligne flere kolonner vertikalt for å forstå innholdet, også på mobil.
+Andre ganger lar innholdet seg legges oppå hverandre i høyden på små skjermer uten at det går for mye ut over lesbarheten.
+Alternativt kan vi bruke en graf for å presentere innhold på mobil, dersom mulig.
+
+De to vanligste tabellene som brukes på mobil er
+- en tabell som ruller horisontalt
+- en tabell som blir gjort om til en listevisning
+
+## Universell utforming
+
+På små skjermer vil endre-ikon flyttes til venstre, og tabellen har horisontal scrolling ved behov. 
+- `Table.HeaderCell` skal brukes på kolonneoverskrifter. Kan også brukes på radoverskrifter for at brukerne skal kunne navigere mer 
+effektivt i tabellen med skjermleser. Husk å bruke `scope="row"` og `scope="col"`. 
+- Tomme celler skal være `Table.Cell`. 
+- Sjekk at du kan velge ulik sortering med tastatur. 
+- Test med skjermleser at du hører hva som er sorterbart, typer sortering og at du ikke mister fokus når du endrer sortering. 
+- Tabeller skal alltid ha et caption-element med kort tekst om hva tabellen viser.
+Skjermlesere vil lese caption-elementet og brukerne kan ta stilling til om de vil lese videre i tabellen.
+
 ## `TableHeaderCell` Props
 
 <ArgTypes of={TableHeaderCell} />

packages/react/src/components/Table/Table.stories.tsx

@@ -263,3 +263,32 @@ export const WithFormElements: Story = (args) => {
     </Table>
   );
 };
+
+export const FixedTable: Story = (args) => {
+  const rows = Array.from({ length: 3 }, (_, i) => i + 1);
+  return (
+    <Table
+      {...args}
+      style={{
+        tableLayout: 'fixed',
+      }}
+    >
+      <TableHead>
+        <TableRow>
+          <TableHeaderCell>Header 1</TableHeaderCell>
+          <TableHeaderCell>Header 2</TableHeaderCell>
+          <TableHeaderCell>Header 3</TableHeaderCell>
+        </TableRow>
+      </TableHead>
+      <TableBody>
+        {rows.map((row) => (
+          <TableRow key={row}>
+            <TableCell>{`Cell ${row}1`}</TableCell>
+            <TableCell>{`Cell ${row}2`}</TableCell>
+            <TableCell>{`Cell ${row}3`}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+};