@irozon/design-system-react 0.1.2 → 0.2.0

package/README.md

@@ -1,63 +1,42 @@
 # @irozon/design-system-react
 
-Canonical React components for the Irozon Design System — thin,
-accessible wrappers over [`@irozon/design-system`](https://www.npmjs.com/package/@irozon/design-system)'s
-framework-neutral `iz-*` CSS.
+React components for the Irozon Design System, built on the same
+framework-neutral CSS as `@irozon/design-system`.
 
-```text
-@irozon/design-tokens
-  ↓
-@irozon/design-system         framework-neutral CSS primitives
-  ↓
-@irozon/design-system-react   canonical React components  ← you are here
-  ↓
-Irozon React applications
-```
-
-## Why this exists
+## Install
 
-`@irozon/design-system` ships CSS, not React — every product that needed
-a `<Button>` was hand-rolling its own thin wrapper around `.iz-button`
-with its own prop names (`variant="danger"`, `size="sm"`, …). This
-package is the single canonical React API, so that stops happening: one
-`<Button variant="destructive" size="small">`, not N slightly-different
-re-implementations of the same markup.
+```bash
+npm install @irozon/design-system-react @irozon/design-system
+```
 
-**This package owns presentation and accessibility wiring only.** It has
-no visual styling of its own (zero CSS shipped — every class it renders
-comes from `@irozon/design-system`), no business/domain logic, and no
-app-specific state (a toast's auto-dismiss *timing* is here because every
-known consumer wants the same default; the toast *list* — what's
-currently showing — is the app's own state. See each component's own
-doc comment for where that line is drawn).
+## Quick start
 
-## Installation
+```tsx
+import "@irozon/design-system/irozon.css";
+import { Button } from "@irozon/design-system-react";
 
-```bash
-npm install @irozon/design-system-react @irozon/design-system
+export function SaveButton() {
+  return <Button variant="primary">Save</Button>;
+}
 ```
 
-`react` and `react-dom` (>=18) are peer dependencies — this package
-never bundles its own copy of React.
+Import the CSS once in your application entry point. The React package ships
+components, while `@irozon/design-system` remains the source of their visual
+styles.
 
-You still need the CSS import from `@irozon/design-system` once per app
-(see that package's own README) — this package only supplies the
-components that render the classes it defines.
+## What it provides
 
-## Usage
+- Typed React components for the Irozon Design System's shared UI.
+- Accessible markup and state wiring for the underlying `iz-*` CSS classes.
+- Native element props alongside the documented design-system props.
+- No business logic or application-specific state.
 
-```tsx
-import { Button, FormField, Input } from "@irozon/design-system-react";
+For example, fields compose naturally from the exported components:
 
-function SaveButton() {
-  return (
-    <Button variant="primary" onClick={handleSave}>
-      Save
-    </Button>
-  );
-}
+```tsx
+import { FormField, Input } from "@irozon/design-system-react";
 
-function EmailField() {
+export function EmailField() {
   return (
     <FormField label="Email" hint="We'll never share it">
       <Input type="email" name="email" />
@@ -66,6 +45,25 @@ function EmailField() {
 }
 ```
 
+## Full documentation
+
+Visit the [Irozon Design System documentation](https://branding.irozon.se/)
+for React usage, component behavior, foundations, tokens, examples, and
+accessibility guidance.
+
+## Related Irozon packages
+
+```text
+@irozon/design-tokens         Design foundations and CSS variables
+  ↓
+@irozon/design-system         Framework-neutral component CSS
+  ↓
+@irozon/design-system-react   React components using the same system ← you are here
+```
+
+`@irozon/design-system-react` depends on `@irozon/design-system`, but install
+both packages because your app imports the CSS package directly.
+
 ## Components
 
 | Component | Wraps |
@@ -80,12 +78,47 @@ function EmailField() {
 | `Toast`, `ToastRegion` | `.iz-toast`, `.iz-toast-region` |
 | `ThemeToggle` | `.iz-theme-toggle` |
 | `Nav`, `NavGroup`, `NavItem` | `.iz-nav`, `.iz-nav-group`, `.iz-nav-item` |
+| `Tabs`, `TabPanel` | `.iz-tabs`, `.iz-tab`, `.iz-tab-panel` |
+
+`Tabs`/`TabPanel` implement the full WAI-ARIA Tabs pattern (automatic
+activation): a roving tabindex so only the selected tab sits in the page's Tab
+order, ArrowLeft/ArrowRight to move between tabs, Home/End to jump to the
+first/last, and a plain click. Pair them via a shared `idPrefix`:
+
+```tsx
+import { useState } from "react";
+import { Tabs, TabPanel } from "@irozon/design-system-react";
+
+function Example() {
+  const [tab, setTab] = useState("overview");
+  return (
+    <>
+      <Tabs
+        idPrefix="example"
+        aria-label="Example sections"
+        value={tab}
+        onValueChange={setTab}
+        tabs={[
+          { value: "overview", label: "Overview" },
+          { value: "details", label: "Details" },
+        ]}
+      />
+      <TabPanel idPrefix="example" value="overview" activeValue={tab}>
+        Overview content
+      </TabPanel>
+      <TabPanel idPrefix="example" value="details" activeValue={tab}>
+        Details content
+      </TabPanel>
+    </>
+  );
+}
+```
+
+The [component documentation](https://branding.irozon.se/components/overview.html)
+includes live examples and React usage. TypeScript declarations in the
+package provide the complete prop types.
 
-Full prop reference: each component's own `.tsx` doc comment, and the
-"React usage" section on the matching page at
-[branding.irozon.se/components](https://branding.irozon.se/components/overview.html) —
-that site remains the canonical visual/behavioral reference; this
-package is the implementation of the same contract.
+## Advanced usage
 
 ### Routed navigation
 
@@ -102,14 +135,14 @@ import { NavItem } from "@irozon/design-system-react";
 </NavItem>;
 ```
 
-## Canonical API, not per-app aliases
+### Canonical API
 
 Prop names and values match the CSS package's own vocabulary exactly —
 `variant="destructive"`, not `variant="danger"`; `size="small"`, not
 `size="sm"`. Product apps migrating from a local wrapper should adopt
 these names at the call sites, not keep a permanent translation layer.
 
-## What this package deliberately does not do
+### Package boundaries
 
 - No CSS of its own — if a component looks wrong, the fix belongs in
   `@irozon/design-system`, not here.
@@ -117,3 +150,15 @@ these names at the call sites, not keep a permanent translation layer.
   persistence, form validation — all owned by the consuming app.
 - No business/domain logic — nothing here knows what an "invoice" or a
   "proposal" is.
+
+React and React DOM `>=18.0.0` are peer dependencies and are not bundled.
+
+## Versioning and compatibility
+
+This package is currently in `0.x` and uses the component vocabulary from
+`@irozon/design-system`. Minor releases may introduce API changes before
+`1.0.0`; check the release notes when upgrading.
+
+## License
+
+MIT © Irozon AB

package/dist/Tabs.d.ts

@@ -0,0 +1,39 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export interface TabItem {
+    value: string;
+    label: ReactNode;
+}
+export interface TabsProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    tabs: TabItem[];
+    value: string;
+    onValueChange: (value: string) => void;
+    /** Shared with `TabPanel` to derive matching tab/panel ids — see `tabId`/`tabPanelId`. */
+    idPrefix: string;
+    variant?: "stretched";
+    /** Required — a tablist needs an accessible name distinguishing it from any other on the page. */
+    "aria-label": string;
+}
+export declare function tabId(idPrefix: string, value: string): string;
+export declare function tabPanelId(idPrefix: string, value: string): string;
+/**
+ * Canonical `.iz-tabs` / `.iz-tab` — the WAI-ARIA Tabs pattern with automatic
+ * activation: a roving tabindex (only the selected tab is in the normal Tab order),
+ * ArrowLeft/ArrowRight move focus and selection together between tabs, Home/End jump
+ * to the first/last tab. Mouse click selects directly. Compose with `TabPanel`,
+ * matched via a shared `idPrefix` — see `tabs.css`'s own doc comment for the markup
+ * shape this renders.
+ */
+export declare function Tabs({ tabs, value, onValueChange, idPrefix, variant, className, ...rest }: TabsProps): import("react").JSX.Element;
+export interface TabPanelProps extends HTMLAttributes<HTMLDivElement> {
+    idPrefix: string;
+    value: string;
+    activeValue: string;
+    children: ReactNode;
+}
+/**
+ * Canonical `.iz-tab-panel` — rendered only while its `value` matches the currently
+ * active tab (unmounted otherwise, not just hidden). `id`/`aria-labelledby` are
+ * derived the same way `Tabs` derives its own tab ids, so pairing a panel with its
+ * tab only requires passing the same `idPrefix` and `value` to both.
+ */
+export declare function TabPanel({ idPrefix, value, activeValue, className, children, ...rest }: TabPanelProps): import("react").JSX.Element | null;

package/dist/Tabs.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from "react";
+import { cx } from "./internal/cx.js";
+export function tabId(idPrefix, value) {
+    return `${idPrefix}-tab-${value}`;
+}
+export function tabPanelId(idPrefix, value) {
+    return `${idPrefix}-panel-${value}`;
+}
+/**
+ * Canonical `.iz-tabs` / `.iz-tab` — the WAI-ARIA Tabs pattern with automatic
+ * activation: a roving tabindex (only the selected tab is in the normal Tab order),
+ * ArrowLeft/ArrowRight move focus and selection together between tabs, Home/End jump
+ * to the first/last tab. Mouse click selects directly. Compose with `TabPanel`,
+ * matched via a shared `idPrefix` — see `tabs.css`'s own doc comment for the markup
+ * shape this renders.
+ */
+export function Tabs({ tabs, value, onValueChange, idPrefix, variant, className, ...rest }) {
+    const buttonRefs = useRef(new Map());
+    function focusAndSelect(index) {
+        const next = tabs[(index + tabs.length) % tabs.length];
+        if (!next)
+            return;
+        onValueChange(next.value);
+        buttonRefs.current.get(next.value)?.focus();
+    }
+    function handleKeyDown(event, index) {
+        switch (event.key) {
+            case "ArrowRight":
+                event.preventDefault();
+                focusAndSelect(index + 1);
+                break;
+            case "ArrowLeft":
+                event.preventDefault();
+                focusAndSelect(index - 1);
+                break;
+            case "Home":
+                event.preventDefault();
+                focusAndSelect(0);
+                break;
+            case "End":
+                event.preventDefault();
+                focusAndSelect(tabs.length - 1);
+                break;
+            default:
+                break;
+        }
+    }
+    return (_jsx("div", { className: cx("iz-tabs", className), role: "tablist", "data-variant": variant, ...rest, children: tabs.map((tab, index) => {
+            const selected = tab.value === value;
+            return (_jsx("button", { ref: (el) => {
+                    if (el)
+                        buttonRefs.current.set(tab.value, el);
+                    else
+                        buttonRefs.current.delete(tab.value);
+                }, type: "button", role: "tab", id: tabId(idPrefix, tab.value), "aria-selected": selected, "aria-controls": tabPanelId(idPrefix, tab.value), tabIndex: selected ? 0 : -1, className: "iz-tab", onClick: () => onValueChange(tab.value), onKeyDown: (event) => handleKeyDown(event, index), children: tab.label }, tab.value));
+        }) }));
+}
+/**
+ * Canonical `.iz-tab-panel` — rendered only while its `value` matches the currently
+ * active tab (unmounted otherwise, not just hidden). `id`/`aria-labelledby` are
+ * derived the same way `Tabs` derives its own tab ids, so pairing a panel with its
+ * tab only requires passing the same `idPrefix` and `value` to both.
+ */
+export function TabPanel({ idPrefix, value, activeValue, className, children, ...rest }) {
+    if (value !== activeValue)
+        return null;
+    return (_jsx("div", { className: cx("iz-tab-panel", className), role: "tabpanel", id: tabPanelId(idPrefix, value), "aria-labelledby": tabId(idPrefix, value), tabIndex: 0, ...rest, children: children }));
+}

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export { ThemeToggle } from "./ThemeToggle.js";
 export type { ThemeToggleProps } from "./ThemeToggle.js";
 export { Nav, NavGroup, NavItem } from "./Nav.js";
 export type { NavProps, NavGroupProps, NavItemProps } from "./Nav.js";
+export { Tabs, TabPanel, tabId, tabPanelId } from "./Tabs.js";
+export type { TabsProps, TabPanelProps, TabItem } from "./Tabs.js";

package/dist/index.js

@@ -8,3 +8,4 @@ export { ConfirmDialog } from "./ConfirmDialog.js";
 export { Toast, ToastRegion } from "./Toast.js";
 export { ThemeToggle } from "./ThemeToggle.js";
 export { Nav, NavGroup, NavItem } from "./Nav.js";
+export { Tabs, TabPanel, tabId, tabPanelId } from "./Tabs.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irozon/design-system-react",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Canonical React components for the Irozon Design System — thin, accessible wrappers over @irozon/design-system's framework-neutral iz-* CSS. No independent visual styling of its own; the CSS package stays the single source of truth for how these look.",
   "license": "MIT",
   "keywords": [