@pokela/components 2.12.0 → 2.13.0

package/README.md

@@ -1,6 +1,6 @@
 # @pokela/components
 
-React-komponentit: **Pokela Design System**, versio 2.12.0.
+React-komponentit: **Pokela Design System**, versio 2.13.0.
 
 > Generoitu hakemistosta `components/` — samoista tiedostoista joita sivusto
 > ajaa. Älä muokkaa käsin: muutokset tehdään lähteeseen ja paketti
@@ -31,6 +31,8 @@ tyylit saa myös suoraan: `@pokela/components/styles.css`.
 - `Switch`
 - `ChoiceGroup`
 - `Select`
+- `Tabs`
+- `Tab`
 - `Grid`
 - `Reveal`
 - `ThemeScript`
@@ -69,6 +71,7 @@ import Link from 'next/link';
 - `styles/text-field.css`
 - `styles/choice.css`
 - `styles/select.css`
+- `styles/tabs.css`
 
 Luokat ovat globaaleja, eivät CSS-moduuleja. Se on tarkoituksellista: sama
 luokka on myös Figmassa komponentin nimenä, ja hajautettu nimi katkaisisi

package/Tab.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+/**
+ * Yksi välilehti ja sen paneeli. Käytetään vain `Tabs`in lapsena.
+ *
+ * Tab ei piirrä itse mitään: `Tabs` lukee sen propsit ja rakentaa
+ * niistä välilehtirivin ja paneelit, jotta ARIA-kytkennät (id:t,
+ * aria-controls, aria-labelledby) syntyvät yhdessä paikassa. Erillinen
+ * komponentti on silti tarpeen, koska kirjoitettuna se on luettavampi
+ * kuin taulukko, ja Figman Tabs / Tab -instanssi kääntyy tähän.
+ */
+export type TabProps = {
+    /** Tunniste, jolla `Tabs` tietää valitun välilehden. */
+    value: string;
+    /** Välilehden teksti. */
+    label: string;
+    /** Lukumäärä tekstin perässä, esim. avoimet tehtävät. */
+    count?: number;
+    disabled?: boolean;
+    /** Paneelin sisältö. */
+    children?: ReactNode;
+};
+export default function Tab(props: TabProps): import("react/jsx-runtime").JSX.Element;

package/Tab.js

@@ -0,0 +1,6 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+export default function Tab(props) {
+    /* Piirretään vain Tabsin kautta. Yksinään paneelin sisältö näkyy
+       sellaisenaan, ettei mitään katoa hiljaa. */
+    return _jsx(_Fragment, { children: props.children });
+}

package/Tabs.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from 'react';
+/**
+ * Välilehdet: rivi välilehtiä ja valitun paneeli.
+ *
+ * Sovelluskomponentti (päätökset 22 ja 28). Ulkoasu on navin
+ * aktiivisen linkin kieli: valittu välilehti saa musteviivan
+ * (--hairline-strong) rivin hiusviivan päälle, muut ovat haaleampia.
+ *
+ * Rakenne WAI-ARIA APG:n Tabs-mallin mukaan, automaattinen aktivointi:
+ *
+ *   rivi      role="tablist", aria-label
+ *   välilehti role="tab", aria-selected, aria-controls. Vain valittu
+ *             on sarkainjärjestyksessä (roving tabindex).
+ *   paneeli   role="tabpanel", aria-labelledby, tabindex=0, jotta
+ *             sarkain vie paneeliin silloinkin, kun siinä ei ole
+ *             fokusoitavaa.
+ *
+ * Näppäimet: vasen ja oikea nuoli siirtävät ja valitsevat (rivin
+ * päästä toiseen), Home ja End vievät päihin. Pois käytöstä olevat
+ * ohitetaan. Paneelit vaihtuvat heti, joten valinta seuraa fokusta.
+ */
+export type TabsProps = {
+    /** Rivin nimi ruudunlukijalle, esim. "Asetukset". Ei näy. */
+    label: string;
+    /** Ohjattu valinta. Käytä `onChange`:n kanssa. */
+    value?: string;
+    /** Alkuvalinta, kun valintaa ei ohjata. Oletus: ensimmäinen käytössä oleva. */
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** `Tab`-elementit. */
+    children: ReactNode;
+    id?: string;
+    className?: string;
+};
+export default function Tabs({ label, value: ohjattu, defaultValue, onChange, children, id: annettuId, className }: TabsProps): import("react/jsx-runtime").JSX.Element;

package/Tabs.js

@@ -0,0 +1,59 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, isValidElement, useId, useRef, useState } from 'react';
+import Tab from './Tab';
+export default function Tabs({ label, value: ohjattu, defaultValue, onChange, children, id: annettuId, className }) {
+    const omaId = useId();
+    const id = annettuId ?? omaId;
+    const tabId = (i) => `${id}-tab-${i}`;
+    const paneeliId = (i) => `${id}-paneeli-${i}`;
+    const tabit = Children.toArray(children).filter((c) => isValidElement(c) && c.type === Tab);
+    const kaytossa = (i) => i >= 0 && i < tabit.length && !tabit[i].props.disabled;
+    const [oma, setOma] = useState(defaultValue);
+    const pyydetty = ohjattu !== undefined ? ohjattu : oma;
+    let valittu = tabit.findIndex((t) => t.props.value === pyydetty);
+    if (!kaytossa(valittu))
+        valittu = tabit.findIndex((_, i) => kaytossa(i));
+    const napit = useRef([]);
+    const valitse = (i) => {
+        if (!kaytossa(i))
+            return;
+        const uusi = tabit[i].props.value;
+        if (ohjattu === undefined)
+            setOma(uusi);
+        if (i !== valittu)
+            onChange?.(uusi);
+    };
+    /** Seuraava käytössä oleva suuntaan `askel`, rivin päästä toiseen. */
+    const seuraava = (alku, askel) => {
+        const n = tabit.length;
+        for (let k = 1; k <= n; k++) {
+            const i = (((alku + askel * k) % n) + n) % n;
+            if (kaytossa(i))
+                return i;
+        }
+        return alku;
+    };
+    const nappain = (e) => {
+        let kohde = -1;
+        if (e.key === 'ArrowRight')
+            kohde = seuraava(valittu, 1);
+        else if (e.key === 'ArrowLeft')
+            kohde = seuraava(valittu, -1);
+        else if (e.key === 'Home')
+            kohde = seuraava(-1, 1);
+        else if (e.key === 'End')
+            kohde = seuraava(tabit.length, -1);
+        else
+            return;
+        e.preventDefault();
+        valitse(kohde);
+        napit.current[kohde]?.focus();
+    };
+    return (_jsxs("div", { className: ['tabs', className].filter(Boolean).join(' '), children: [_jsx("div", { className: "tabs__list", role: "tablist", "aria-label": label, onKeyDown: nappain, children: tabit.map((t, i) => {
+                    const on = i === valittu;
+                    return (_jsxs("button", { ref: (el) => {
+                            napit.current[i] = el;
+                        }, type: "button", role: "tab", id: tabId(i), className: "tabs__tab", "aria-selected": on, "aria-controls": paneeliId(i), "aria-disabled": t.props.disabled || undefined, tabIndex: on ? 0 : -1, onClick: () => valitse(i), children: [t.props.label, t.props.count !== undefined ? _jsx("span", { className: "tabs__count", children: t.props.count }) : null] }, t.props.value));
+                }) }), tabit.map((t, i) => (_jsx("div", { role: "tabpanel", id: paneeliId(i), className: "tabs__panel", "aria-labelledby": tabId(i), tabIndex: 0, hidden: i !== valittu, children: t.props.children }, t.props.value)))] }));
+}

package/guidelines/components.md

@@ -16,6 +16,8 @@ Use these instead of building an equivalent.
 - `Switch`
 - `ChoiceGroup`
 - `Select`
+- `Tabs`
+- `Tab`
 - `Grid`, `Col`
 - `Reveal`
 - `ThemeScript`, `THEME_STORAGE_KEY`
@@ -128,6 +130,22 @@ work, so do not build a dropdown from a button and a menu.
 />
 ```
 
+`Tabs` switches between views of the same thing, such as the sections of a
+settings page. Give it a `label` for screen readers and one `Tab` per view with
+`value`, `label` and the panel as children; `count` adds a number after the
+label and `disabled` keeps a tab visible but unusable. It follows the WAI-ARIA
+tabs pattern: arrow keys move and select, Home and End jump to the ends, and
+Tab moves into the panel. Do not use it for site navigation (that is `Nav`) or
+for a step-by-step flow.
+
+```jsx
+<Tabs label="Settings" defaultValue="team">
+  <Tab value="general" label="General">…</Tab>
+  <Tab value="team" label="Team" count={4}>…</Tab>
+  <Tab value="billing" label="Billing" disabled>…</Tab>
+</Tabs>
+```
+
 ## Patterns
 
 `PageHeader` and `Section` are patterns: they add no look of their own, only

package/index.d.ts

@@ -24,6 +24,10 @@ export { default as ChoiceGroup } from './ChoiceGroup.js';
 export type { ChoiceGroupProps } from './ChoiceGroup.js';
 export { default as Select } from './Select.js';
 export type { SelectOption, SelectProps } from './Select.js';
+export { default as Tabs } from './Tabs.js';
+export type { TabsProps } from './Tabs.js';
+export { default as Tab } from './Tab.js';
+export type { TabProps } from './Tab.js';
 export { Grid, Col } from './Grid.js';
 export { default as Reveal } from './Reveal.js';
 export { default as ThemeScript, THEME_STORAGE_KEY } from './ThemeScript.js';

package/index.js

@@ -13,6 +13,8 @@ export { default as Radio } from './Radio.js';
 export { default as Switch } from './Switch.js';
 export { default as ChoiceGroup } from './ChoiceGroup.js';
 export { default as Select } from './Select.js';
+export { default as Tabs } from './Tabs.js';
+export { default as Tab } from './Tab.js';
 export { Grid, Col } from './Grid.js';
 export { default as Reveal } from './Reveal.js';
 export { default as ThemeScript, THEME_STORAGE_KEY } from './ThemeScript.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokela/components",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "React-komponentit: Pokela Design System. Generoitu tiedostoista components/, ei käsin ylläpidetty.",
   "license": "MIT",
   "author": "Veli-Matti Pokela",
@@ -27,7 +27,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@pokela/tokens": "^2.12.0"
+    "@pokela/tokens": "^2.13.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/styles/tabs.css

@@ -0,0 +1,83 @@
+/* Välilehdet (Tabs). Sovelluskomponentti, sivusto ei käytä tätä.
+   ==================================================================
+   Navin aktiivisen linkin kieli (päätös 28): rivi välilehtiä
+   hiusviivan päällä, valittu saa musteviivan --hairline-strong, joka
+   peittää hiusviivan. Valitsematon on --ink-muted ja tummuu hoverissa.
+
+   Välilehdellä on 8 px sivusisennys, jotta fokusrengas mahtuu sen
+   sisään: rivi vierittyy kapealla näytöllä, ja vierittyvä laatikko
+   leikkaisi ulkopuolisen renkaan. Sisennys kumotaan rivin
+   negatiivisella marginaalilla, joten teksti alkaa palstan reunasta.
+   Siksi hiusviiva on taustana eikä reunana: reuna jatkuisi 8 px yli. */
+
+.tabs__list {
+  display: flex;
+  gap: var(--space-16);
+  margin-inline: calc(var(--space-8) * -1);
+  overflow-x: auto;
+  scrollbar-width: none;
+  background: linear-gradient(var(--line), var(--line)) no-repeat var(--space-8) 100% /
+    calc(100% - var(--space-16)) var(--hairline);
+}
+.tabs__list::-webkit-scrollbar { display: none; }
+
+.tabs__tab {
+  position: relative;
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-8);
+  min-height: var(--tap-min);
+  padding: 0 var(--space-8);
+  margin: 0;
+  background: none;
+  border: 0;
+  font-family: var(--font-ui);
+  font-size: var(--text-body-s);
+  font-weight: var(--weight-500);
+  line-height: 1;
+  color: var(--ink-muted);
+  white-space: nowrap;
+  cursor: pointer;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .tabs__tab { transition: color var(--dur-fast) var(--ease-standard); }
+}
+.tabs__tab::after {
+  content: '';
+  position: absolute;
+  left: var(--space-8);
+  right: var(--space-8);
+  bottom: 0;
+  height: var(--hairline-strong);
+}
+.tabs__tab:hover { color: var(--ink); }
+.tabs__tab[aria-selected='true'] { color: var(--ink); }
+.tabs__tab[aria-selected='true']::after { background: var(--ink); }
+.tabs__tab:focus-visible {
+  outline: var(--focus-width) solid var(--ink);
+  outline-offset: calc(var(--focus-width) * -1);
+}
+.tabs__tab[aria-disabled='true'] { color: var(--ink-faint); cursor: not-allowed; }
+
+.tabs__count {
+  font-size: var(--text-meta-s);
+  font-weight: var(--weight-600);
+  font-variant-numeric: tabular-nums;
+  color: var(--ink-faint);
+}
+.tabs__tab[aria-selected='true'] .tabs__count { color: var(--ink-muted); }
+
+.tabs__panel { padding-top: var(--space-24); }
+.tabs__panel:focus-visible {
+  outline: var(--focus-width) solid var(--ink);
+  outline-offset: var(--focus-offset);
+}
+
+/* Korkean kontrastin tilassa taustat katoavat: valinnan viiva
+   piirretään järjestelmän värillä. */
+@media (forced-colors: active) {
+  .tabs__tab::after { forced-color-adjust: none; }
+  .tabs__tab[aria-selected='true']::after { background: Highlight; }
+  .tabs__tab[aria-disabled='true'] { color: GrayText; }
+}

package/styles.css

@@ -11,3 +11,4 @@
 @import './styles/text-field.css';
 @import './styles/choice.css';
 @import './styles/select.css';
+@import './styles/tabs.css';