@tapestry-ui/tabs 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Minton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @tapestry-ui/tabs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A WCAG 2.1 AA tab set for **Preact**. Headless behavior, skin via CSS.
+Third citizen of Tapestry UI, after
+[@tapestry-ui/accordion](https://www.npmjs.com/package/@tapestry-ui/accordion)
+and [@tapestry-ui/modal](https://www.npmjs.com/package/@tapestry-ui/modal).
+
+```sh
+npm i @tapestry-ui/tabs
+```
+
+```tsx
+import { Tabs } from '@tapestry-ui/tabs';
+import '@tapestry-ui/tabs/styles.css';   // structural only — optional
+
+<Tabs
+  label="Dashboard sections"
+  items={[
+    { id: 'lodge', label: 'The Lodge', content: <LodgeTab /> },
+    { id: 'eig',   label: 'Entelechy', content: <CompanyTab /> },
+  ]}
+/>
+
+// controlled, when the URL or a parent owns the selection
+<Tabs label="…" items={items} value={tab} onChange={setTab} />
+```
+
+## Accessibility (WCAG 2.1 AA by design, not by audit)
+- The strip is **one tab stop**. A roving `tabindex` puts the selected tab
+  in the page's tab order and takes the others out, so Tab moves past the
+  whole set the way the WAI-ARIA pattern requires.
+- **Arrow keys** move between tabs, wrapping; **Home**/**End** jump to the
+  ends. Disabled tabs are skipped, never landed on.
+- `role="tablist"` / `role="tab"` / `role="tabpanel"`, with `aria-selected`,
+  `aria-controls` and `aria-labelledby` wired both ways.
+- `label` is required and becomes the tablist's accessible name — a strip
+  of unnamed tabs tells a screen-reader user nothing.
+- The panel carries `tabIndex={0}` so a keyboard can reach and scroll it.
+- `:focus-visible` outlines ship in the structural CSS and are yours to
+  restyle, never to remove.
+
+## Automatic vs manual activation
+`activation="automatic"` (default) selects as focus moves — the pattern's
+advice when panels are cheap to render. Pass `activation="manual"` when a
+panel costs something (a fetch, a chart): arrows then move focus only, and
+Enter or Space selects.
+
+## Only the selected panel renders
+Unselected panels are **absent from the DOM**, not hidden — the same ruling
+`@tapestry-ui/accordion` makes about closed bodies. Two consequences worth
+knowing: a panel's component state resets when you leave and come back, and
+nothing invisible is left for assistive tech to walk through.
+
+## ⭐ The container contract
+A tab set never owns scrolling and never constrains its panel. When panel
+content can exceed the space, some ancestor **you choose** must be the
+scroll region:
+
+```css
+.my-panel-wrapper {        /* ONE scrollable region… */
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;        /* …owns ALL the growth */
+}
+```
+
+Putting a tab set inside `@tapestry-ui/modal` gives you that for free: the
+modal's middle is already the one scrollable region.
+
+## Theming
+Structural CSS only — nothing here picks a color.
+
+| custom property | default | what it tunes |
+| --- | --- | --- |
+| `--tui-tabs-gap` | `0.5em` | space between tabs |
+| `--tui-tabs-tab-pad` | `0.4em 0.8em` | padding inside each tab |
+| `--tui-tabs-focus` | `2px solid currentColor` | the focus ring |
+
+Style `[data-part="root" \| "list" \| "tab" \| "panel"]` and
+`[data-state="selected" \| "idle"]` for anything deeper.
+
+## License
+MIT © Brandon Minton

package/dist/tabs.d.ts

@@ -0,0 +1,28 @@
+import { type ComponentChildren, type JSX } from 'preact';
+export interface TabItem {
+    /** stable id — defaults to the item's position, so reordering data without
+     *  ids will move the selection; give real ids when the list can change */
+    id?: string;
+    label: ComponentChildren;
+    content: ComponentChildren;
+    disabled?: boolean;
+}
+export interface TabsProps {
+    items: TabItem[];
+    /** accessible name for the strip: assistive tech announces it before the tabs */
+    label: string;
+    /** uncontrolled initial selection (default: the first enabled tab) */
+    defaultValue?: string;
+    /** controlled selection — the component follows it and only reports intent */
+    value?: string;
+    onChange?: (id: string) => void;
+    /** 'automatic' (default) selects on focus; 'manual' waits for Enter/Space */
+    activation?: 'automatic' | 'manual';
+    /** skin hooks — tapestry-ui components style through CSS, never props */
+    class?: string;
+    listClass?: string;
+    tabClass?: string;
+    panelClass?: string;
+    id?: string;
+}
+export declare function Tabs(props: TabsProps): JSX.Element;

package/dist/tabs.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { useId, useRef, useState } from 'preact/hooks';
+export function Tabs(props) {
+    const autoId = useId();
+    const base = props.id ?? `tui-tabs-${autoId}`;
+    const ids = props.items.map((item, index) => item.id ?? `${base}-${index}`);
+    const listRef = useRef(null);
+    const firstEnabledIndex = props.items.findIndex((item) => !item.disabled);
+    const controlled = props.value !== undefined;
+    const [ownValue, setOwnValue] = useState(props.defaultValue ?? ids[firstEnabledIndex === -1 ? 0 : firstEnabledIndex]);
+    const current = controlled ? props.value : ownValue;
+    const foundIndex = ids.indexOf(current);
+    const selectedIndex = foundIndex === -1 ? (firstEnabledIndex === -1 ? 0 : firstEnabledIndex) : foundIndex;
+    const select = (index) => {
+        const item = props.items[index];
+        if (!item || item.disabled)
+            return;
+        if (!controlled)
+            setOwnValue(ids[index]);
+        props.onChange?.(ids[index]);
+    };
+    const focusTab = (index) => {
+        listRef.current?.querySelectorAll('[data-part="tab"]')[index]?.focus();
+    };
+    /** the next enabled tab in `step` direction, wrapping; a disabled tab is never a destination */
+    const nextEnabled = (from, step) => {
+        const count = props.items.length;
+        for (let hop = 1; hop <= count; hop++) {
+            const index = (((from + step * hop) % count) + count) % count;
+            if (!props.items[index].disabled)
+                return index;
+        }
+        return from;
+    };
+    const handleKey = (event, index) => {
+        const moveTo = {
+            ArrowRight: () => nextEnabled(index, 1),
+            ArrowLeft: () => nextEnabled(index, -1),
+            Home: () => nextEnabled(-1, 1),
+            End: () => nextEnabled(0, -1),
+        };
+        const move = moveTo[event.key];
+        if (move) {
+            event.preventDefault();
+            const target = move();
+            focusTab(target);
+            if (props.activation !== 'manual')
+                select(target);
+            return;
+        }
+        // automatic activation already selected on focus; manual waits to be told
+        const isActivating = event.key === 'Enter' || event.key === ' ';
+        if (isActivating && props.activation === 'manual') {
+            event.preventDefault();
+            select(index);
+        }
+    };
+    const selected = props.items[selectedIndex];
+    return (_jsxs("div", { id: base, class: cx('tui-tabs', props.class), "data-part": "root", children: [_jsx("div", { ref: listRef, class: cx('tui-tabs__list', props.listClass), "data-part": "list", role: "tablist", "aria-label": props.label, children: props.items.map((item, index) => {
+                    const isSelected = index === selectedIndex;
+                    return (_jsx("button", { type: "button", role: "tab", "data-part": "tab", "data-state": isSelected ? 'selected' : 'idle', id: `${base}-tab-${index}`, class: cx('tui-tabs__tab', props.tabClass), "aria-selected": isSelected, "aria-controls": `${base}-panel-${index}`, tabIndex: isSelected ? 0 : -1, disabled: item.disabled, onClick: () => select(index), onKeyDown: (event) => handleKey(event, index), children: item.label }, ids[index]));
+                }) }), _jsx("div", { role: "tabpanel", "data-part": "panel", id: `${base}-panel-${selectedIndex}`, class: cx('tui-tabs__panel', props.panelClass), "aria-labelledby": `${base}-tab-${selectedIndex}`, tabIndex: 0, children: selected?.content })] }));
+}
+function cx(...parts) {
+    return parts.filter(Boolean).join(' ');
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@tapestry-ui/tabs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A WCAG 2.1 AA tab set for Preact \u2014 roving tabindex, arrow-key navigation, headless behavior, skin via CSS. Forged inside a woven-tapestry game; ships with its container contract, not just its markup.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/tabs.d.ts",
+      "default": "./dist/tabs.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "preact": ">=10.24.0"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "preact": "^10.29.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryurage/brandonminton.git",
+    "directory": "packages/tapestry-ui/tabs"
+  },
+  "keywords": [
+    "preact",
+    "tabs",
+    "tablist",
+    "a11y",
+    "wcag",
+    "headless",
+    "tapestry-ui"
+  ]
+}

package/styles.css

@@ -0,0 +1,22 @@
+/* @tapestry-ui/tabs — STRUCTURAL styles only. The skin is yours:
+   override the custom properties, or ignore this file entirely and
+   style [data-part] hooks from scratch. Nothing here picks a color. */
+.tui-tabs__list {
+  display: flex;
+  gap: var(--tui-tabs-gap, 0.5em);
+  flex-wrap: wrap;
+}
+.tui-tabs__tab {
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: var(--tui-tabs-tab-pad, 0.4em 0.8em);
+}
+.tui-tabs__tab:disabled { cursor: default; opacity: 0.5; }
+.tui-tabs__tab:focus-visible,
+.tui-tabs__panel:focus-visible {
+  outline: var(--tui-tabs-focus, 2px solid currentColor);
+  outline-offset: 2px;
+}