@torpor/ui 0.0.16 → 0.0.17

package/scripts/postbuild.ts

@@ -1,13 +1,18 @@
 import chalk from "chalk";
 import { existsSync, promises as fs, lstatSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // HACK: There is almost certainly a way to do this with standard TS/TSUP/etc
 // but I can't figure it out
 
 async function run() {
-	const distFolder = resolve(dirname(fileURLToPath(import.meta.url)), "../dist");
+	const scriptsFolder = dirname(fileURLToPath(import.meta.url));
+	const sourceFolder = resolve(scriptsFolder, "../src");
+	const distFolder = resolve(scriptsFolder, "../dist");
+
+	// Read the dist files first, not for every component
+	const distFiles = (await fs.readdir(distFolder)).filter((f) => f.endsWith(".torp"));
 
 	// Loop through component folders e.g. Accordion
 	const componentFolders = (await fs.readdir(distFolder)).filter((f) =>
@@ -27,10 +32,11 @@ async function run() {
 		}
 
 		// Move all *.torp files for the component into this folder
-		const relatedFiles = (await fs.readdir(distFolder)).filter(
-			(f) => f.startsWith(component) && f !== component,
-		);
-		for (const file of relatedFiles) {
+		let relatedFiles = (await fs.readdir(join(sourceFolder, component)))
+			.filter((f) => f.endsWith(".torp") && f !== component)
+			.map((f) => basename(f, ".torp"))
+			.map((f) => distFiles.find((df) => df.startsWith(`${f}-`) && df.endsWith(".torp"))!);
+		for (let file of relatedFiles) {
 			const newfile = file.substring(0, file.indexOf("-")) + ".torp";
 			await fs.rename(join(distFolder, file), join(distFolder, component, newfile));
 		}

package/src/TabGroup/TabContent.torp

@@ -0,0 +1,36 @@
+import getId from '../utils/getId';
+import { TabGroupContextName, type TabGroupContext } from './TabGroupTypes';
+
+/**
+ * Content for a TabGroup, which can be revealed or hidden by an associated TabTrigger.
+ *
+ * @prop {string} [id] -- An ID for the TabContent's div container
+ */
+export default function TabContent($props: any) {
+	$props.id ||= getId();
+
+	const context = $context[TabGroupContextName] as TabGroupContext;
+	if (!context) {
+		throw new Error('TabContent must be contained within a TabGroup');
+	}
+	let $state = $context[TabGroupContextName].registerItem($props.index, $props.value);
+
+	// Set the content ID so that it can be used with aria-controls in TabTrigger
+	$state.contentId = $props.id;
+
+	@render {
+		<div
+			id={$props.id}
+			class='torp-tab-content'
+			role="tabpanel"
+			aria-labelledby={$state.headerId}
+			data-orientation={$props.orientation}
+			data-state={$state.dataState}
+			data-disabled={$state.dataDisabled}
+		>
+			@if ($state.active) {
+				<:slot />
+			}
+		</div>
+	}
+}

package/src/TabGroup/TabGroup.torp

@@ -0,0 +1,226 @@
+import { TabGroupContextName, type TabGroupContext, type ItemState } from './TabGroupTypes';
+
+/**
+ * A list of interactive headings coupled with layered sections of content that
+ * enable users to reveal a single section of content at a time.
+ *
+ * See [the WAI ARIA guidelines for Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ *
+ * The structure of a TabGroup is:
+ *
+ * ```
+ * <TabGroup>
+ * 	<TabList>
+ * 		<TabHeader>
+ * 			<TabTrigger />
+ * 		</TabHeader>
+ * 	</TabList>
+ * 	<TabContent />
+ * </TabGroup>
+ * ```
+ *
+ * @prop {'horizontal' | 'vertical'} orientation -- The orientation of the tab buttons, which affects keyboard navigation
+ * @prop {'automatic' | 'manual'} activation -- How tabs are activated; if automatic they are shown on focus, if manual they must be clicked
+ * @prop {string | string[]} value -- The value of the active TabContent
+ * @prop {boolean} disabled -- If set to true, the user cannot interact with any items in the TabGroup
+ * @prop {(value: string | string[]) => void} [onchange] -- Raised when the active item has changed
+ */
+export default function TabGroup($props: any) {
+	$props.orientation ||= 'horizontal';
+	$props.activation ||= 'automatic';
+	$props.value ||= '';
+
+	interface State {
+		value: string;
+		itemStates: ItemState[];
+	}
+
+	let $state: State = $watch({
+		value: $props.value,
+		itemStates: []
+	})
+
+	// This is used to assign automatic indexes to items where needed
+	let nextHeaderIndex = 0;
+	let nextItemIndex = 0;
+
+	// Set the context to pass down to headers and content, with functions for each item to call
+	let context: TabGroupContext = {
+		registerHeader,
+		registerItem,
+		removeItem,
+		triggerItem,
+		handleHeaderKey,
+		orientation: $props.orientation,
+		activation: $props.activation,
+	};
+	$context[TabGroupContextName] = context;
+
+	$run(() => {
+		// HACK: This should probably be done with setters?
+		let newValue = $state.value;
+
+		// Ensure the value passed in was a string (in case e.g. the user has set values to ints)
+		newValue = newValue?.toString();
+		for (let item of $state.itemStates) {
+			item.active = item.value === newValue;
+		}
+
+		// Set the value
+		$state.value = newValue;
+	});
+
+	$run(() => {
+		$state.itemStates.forEach((s) => s.parentDisabled = $props.disabled);
+	});
+
+	// Dispatch the change event when the value changes
+	// TODO: Should this be a setter instead?
+	$run(() => {
+		if ($props.onchange) {
+			$props.onchange($state.value);
+		}
+	})
+
+	// TODO:
+	//$mount(() => {
+	//	if ($state.value === "" && $state.itemStates.length) {
+	//		$state.value = $state.itemStates[0].value;
+	//	}
+	//})
+
+	function registerHeader(index: number | undefined, value: string | undefined, setFocused: () => void): ItemState {
+		// If an index wasn't set for the header, set it automatically
+		if (!index) {
+			index = nextHeaderIndex++;
+		}
+
+		// Get or add the ItemState at this index
+		const itemState = getItemState(index, value);
+
+		itemState.setFocused = setFocused;
+
+		return itemState;
+	}
+
+	function registerItem(index: number | undefined, value: string | undefined): ItemState {
+		// If an index wasn't set for the item, set it automatically
+		if (!index) {
+			index = nextItemIndex++;
+		}
+
+		// Get or add the ItemState at this index
+		const itemState = getItemState(index, value);
+
+		return itemState;
+	}
+
+	function getItemState(index: number, value: string | undefined): ItemState {
+		// If we already have an item at this index, just return it
+		if ($state.itemStates.length > index) {
+			return $state.itemStates[index];
+		}
+
+		// If a value wasn't set for the item, set it to the index
+		if (!value) {
+			value = index.toString();
+		}
+
+		// Add the item's state to the array
+		const newItemState: ItemState = $watch({
+			index,
+			value,
+			active: value === $state.value,
+			headerId: '',
+			contentId: '',
+			disabled: false,
+			parentDisabled: false,
+			setFocused: () => {},
+			orientation: $props.orientation,
+			activation: $props.activation
+		});
+		$state.itemStates.splice(index, 0, newItemState);
+
+		return newItemState;
+	}
+
+	// TODO: I think this should be done by value
+	function removeItem(itemIndex: number) {
+		// Remove the item and re-index
+		let index = $state.itemStates.findIndex((item) => item.index === itemIndex);
+		if (index !== -1) {
+			$state.itemStates.splice(itemIndex, 1);
+		}
+		$state.itemStates.forEach((item, i) => (item.index = i));
+	}
+
+	function triggerItem(toggleValue: string) {
+		for (let item of $state.itemStates) {
+			// The item is active if it has the supplied value
+			if (item.value === toggleValue) {
+				$state.value = item.value;
+				break;
+			}
+		}
+	}
+
+	function handleHeaderKey(headerIndex: number, e: KeyboardEvent) {
+		switch (e.key) {
+			case 'Left':
+			case 'ArrowLeft': {
+				if ($props.orientation === 'horizontal' && headerIndex > 0) {
+					e.preventDefault();
+					$state.itemStates[headerIndex - 1].setFocused();
+				}
+				break;
+			}
+			case 'Up':
+			case 'ArrowUp': {
+				if ($props.orientation === 'vertical' && headerIndex > 0) {
+					e.preventDefault();
+					$state.itemStates[headerIndex - 1].setFocused();
+				}
+				break;
+			}
+			case 'Right':
+			case 'ArrowRight': {
+				if ($props.orientation === 'horizontal' && headerIndex < $state.itemStates.length - 1) {
+					e.preventDefault();
+					$state.itemStates[headerIndex + 1].setFocused();
+				}
+				break;
+			}
+			case 'Down':
+			case 'ArrowDown': {
+				if ($props.orientation === 'vertical' && headerIndex < $state.itemStates.length - 1) {
+					e.preventDefault();
+					$state.itemStates[headerIndex + 1].setFocused();
+				}
+				break;
+			}
+			case 'Home': {
+				if (headerIndex > 0) {
+					e.preventDefault();
+					$state.itemStates[0].setFocused();
+				}
+				break;
+			}
+			case 'End': {
+				if (headerIndex < $state.itemStates.length - 1) {
+					e.preventDefault();
+					$state.itemStates[$state.itemStates.length - 1].setFocused();
+				}
+				break;
+			}
+		}
+	}
+
+	@render {
+		<div
+			class="torp-tab-group"
+			data-orientation={$props.orientation}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/TabGroup/TabGroupTypes.ts

@@ -0,0 +1,38 @@
+export const TabGroupContextName = "TabGroup";
+export const TabItemContextName = "TabItem";
+
+export interface TabGroupContext {
+	/** Called from a header when it is added */
+	registerHeader: (index: number, value: string, setFocused: () => void) => ItemState;
+	/** Called from an item when it is added */
+	registerItem: (index: number, value: string) => ItemState;
+	/** Called from an item when it is removed */
+	removeItem: (index: number) => void;
+	/** Called from an item when it is triggered */
+	triggerItem: (value: string) => void;
+	/** Called from a TabHeader when it receives a keyboard event */
+	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
+	orientation: "horizontal" | "vertical";
+	activation: "automatic" | "manual";
+}
+
+export interface TabItemContext {
+	/** Called when an item is triggered */
+	triggerItem: (value: string) => void;
+	/** Called when a TabHeader receives a keyboard event */
+	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
+	/** The reactive state for an item */
+	state: ItemState;
+}
+
+export interface ItemState {
+	index: number;
+	value: string;
+	active: boolean;
+	headerId: string;
+	contentId: string;
+	disabled: boolean;
+	parentDisabled: boolean;
+	/** Called in the TabGroup when a header needs to be focused */
+	setFocused: () => void;
+}

package/src/TabGroup/TabHeader.torp

@@ -0,0 +1,60 @@
+import { TabGroupContextName, TabItemContextName, type TabGroupContext, type TabItemContext } from './TabGroupTypes';
+
+/**
+ * The header for a tab item, which contains the TabTrigger.
+ *
+ * The structure of an TabHeader is:
+ * 
+ * ```
+ * <TabHeader>
+ * 	<TabTrigger />
+ * </TabHeader>
+ * ```
+ *
+ * @prop {'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'} as -- The type of HTML header to use
+ */
+export default function TabHeader($props: any) {
+	const context = $context[TabGroupContextName] as TabGroupContext;
+	if (!context) {
+		throw new Error('TabHeader must be contained within a TabGroup');
+	}
+	let $state = $context[TabGroupContextName].registerHeader($props.index, $props.value);
+
+	const itemContext: TabItemContext = {
+		triggerItem: context.triggerItem,
+		handleHeaderKey: context.handleHeaderKey,
+		state: $state,
+	};
+	$context[TabItemContextName] = itemContext;
+
+	// Remove the item from the parent TabGroup when this item is destroyed
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		}
+	});
+
+	@render {
+		@// TODO: $props.as
+		<h4
+			:class={{
+				'torp-tab-header': true,
+				horizontal: $state.orientation === "horizontal",
+				vertical: $state.orientation === "vertical" }}
+			data-state={$state.dataState}
+			data-disabled={$state.dataDisabled}
+		>
+			<:slot />
+		</h4>
+	}
+
+	@style {
+		.torp-tab-header.horizontal {
+			display: inline-block;
+		}
+
+		.torp-tab-header.vertical {
+			display: block;
+		}
+	}
+}

package/src/TabGroup/TabList.torp

@@ -0,0 +1,49 @@
+import { TabGroupContextName, TabItemContextName, type TabGroupContext, type TabItemContext } from './TabGroupTypes';
+
+/**
+ * A component that holds the TabHeaders of a TabGroup.
+ * 
+ * The structure of a TabList is:
+ * 
+ * ```
+ * <TabList>
+ * 	<TabHeader>
+ * 		<TabTrigger />
+ * 	</TabHeader>
+ * </TabList>
+ * ```
+ *
+ * @prop {string} ariaLabel -- An ARIA label for describing the tab list to screen readers
+ */
+export default function TabList($props: any) {
+	// Get stuff out of the TabGroupContext
+	const context = $context[TabGroupContextName] as TabGroupContext;
+	if (!context) {
+		throw new Error('TabList must be contained within an TabGroup');
+	}
+	// TODO: const { orientation } = context;
+	const orientation = context.orientation;
+
+	function handleFocus(e: FocusEvent & { currentTarget: EventTarget & HTMLElement }) {
+		// TODO: Should this be the first button?
+		const el = e.currentTarget.childNodes[0];
+		if (el instanceof HTMLElement) {
+			el.focus();
+			e.preventDefault();
+		}
+	}
+
+	@render {
+		<div
+			class='torp-tab-list'
+			role="tablist"
+			aria-label={$props.ariaLabel}
+			aria-orientation={orientation}
+			data-orientation={orientation}
+			tabindex="0"
+			onfocus={handleFocus}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/TabGroup/TabTrigger.torp

@@ -0,0 +1,65 @@
+import getId from '../utils/getId';
+import { TabItemContextName, type TabItemContext } from './TabGroupTypes';
+
+/**
+ * A header button for a tab item, which can be used to reveal an associated TabContent.
+ */
+export default function TabTrigger() {
+	let button: HTMLButtonElement;
+
+	$props.id ||= getId();
+
+	// Get stuff out of the TabItemContext
+	const context = $context[TabItemContextName] as TabItemContext;
+	if (!context) {
+		throw new Error('TabTrigger must be contained within an TabItem');
+	}
+	let $state = $context[TabItemContextName].state;
+
+	// Set the header ID so that it can be used with aria-labelledby in TabContent
+	$state.headerId = $props.id;
+
+	// Let the item know how to set the button's focus
+	$state.setFocused = setFocused;
+
+	// This function is called by the parent TabGroup to focus this item's button
+	function setFocused() {
+		button.focus();
+		if ($state.activation === 'automatic') {
+			context.triggerItem($state.value);
+		}
+	}
+
+	function handleClick() {
+		// Pass the value to the triggerItem method in the parent TabGroup which will handle toggling
+		// the value of active for all items (e.g. to close other items if necessary)
+		context.triggerItem($state.value);
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		// Pass the key press up to the parent TabGroup which will handle setting the focused button
+		context.handleHeaderKey($state.index, e);
+	}
+
+	@render {
+		<button
+			type="button"
+			id={$props.id}
+			class='torp-tab-trigger'
+			role="tab"
+			tabindex="-1"
+			disabled={$state.disabled || $state.parentDisabled}
+			aria-selected={$state.active.toString()}
+			aria-disabled={$state.disabled}
+			aria-controls={$state.contentId}
+			data-state={$state.dataState}
+			data-disabled={$state.disabled}
+			data-orientation={$state.orientation}
+			:self={button}
+			onclick={handleClick}
+			onkeydown={handleKey}
+		>
+			<:slot />
+		</button>
+	}
+}

package/src/TabGroup/index.ts

@@ -0,0 +1,7 @@
+import TabContent from "./TabContent.torp";
+import TabGroup from "./TabGroup.torp";
+import TabHeader from "./TabHeader.torp";
+import TabList from "./TabList.torp";
+import TabTrigger from "./TabTrigger.torp";
+
+export { TabGroup, TabList, TabHeader, TabTrigger, TabContent };

package/src/TabGroup.ts

@@ -0,0 +1,7 @@
+import TabContent from "./TabGroup/TabContent.torp";
+import TabGroup from "./TabGroup/TabGroup.torp";
+import TabHeader from "./TabGroup/TabHeader.torp";
+import TabList from "./TabGroup/TabList.torp";
+import TabTrigger from "./TabGroup/TabTrigger.torp";
+
+export { TabGroup, TabList, TabHeader, TabTrigger, TabContent };

package/test/TabGroup/accessibility.test.ts

@@ -0,0 +1,67 @@
+import { queryByText } from "@testing-library/dom";
+import "@testing-library/jest-dom/vitest";
+import { mount } from "@torpor/view";
+import { describe, expect, it } from "vitest";
+import TabGroupAccessibility from "./components/TabGroupAccessibility.torp";
+
+describe("TabGroup", () => {
+	it("Accessibility", async () => {
+		const container = document.createElement("div");
+		document.body.appendChild(container);
+		mount(container, TabGroupAccessibility, { value: "0" });
+
+		// Tests from https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+
+		// The element that serves as the container for the set of tabs has role
+		// tablist
+		expect(queryByText(container, "Header 1")?.parentElement?.parentElement).toHaveAttribute(
+			"role",
+			"tablist",
+		);
+
+		// Each element that serves as a tab has role tab and is contained
+		// within the element with role tablist
+		expect(queryByText(container, "Header 1")).toHaveAttribute("role", "tab");
+
+		// Each element that contains the content panel for a tab has role
+		// tabpanel
+		expect(queryByText(container, "Body 1")).toHaveAttribute("role", "tabpanel");
+
+		// If the tab list has a visible label, the element with role tablist
+		// has aria-labelledby set to a value that refers to the labelling
+		// element. Otherwise, the tablist element has a label provided by
+		// aria-label
+		// NOTE: We only support aria-label and it's required
+		expect(queryByText(container, "Header 1")?.parentElement?.parentElement).toHaveAttribute(
+			"aria-label",
+			"Example tabs",
+		);
+
+		// Each element with role tab has the property aria-controls referring
+		// to its associated tabpanel element
+		const tabId = queryByText(container, "Header 1")?.id;
+		const contentId = queryByText(container, "Body 1")?.id;
+		expect(queryByText(container, "Header 1")).toHaveAttribute("aria-controls", contentId);
+
+		// The active tab element has the state aria-selected set to true and
+		// all other tab elements have it set to false
+		expect(queryByText(container, "Header 1")).toHaveAttribute("aria-selected", "true");
+		expect(queryByText(container, "Header 2")).toHaveAttribute("aria-selected", "false");
+		expect(queryByText(container, "Header 3")).toHaveAttribute("aria-selected", "false");
+
+		// Each element with role tabpanel has the property aria-labelledby
+		// referring to its associated tab element
+		expect(queryByText(container, "Body 1")).toHaveAttribute("aria-labelledby", tabId);
+
+		// If a tab element has a popup menu, it has the property aria-haspopup
+		// set to either menu or true
+
+		// If the tablist element is vertically oriented, it has the property
+		// aria-orientation set to vertical. The default value of
+		// aria-orientation for a tablist element is horizontal
+		expect(queryByText(container, "Header 1")?.parentElement?.parentElement).toHaveAttribute(
+			"aria-orientation",
+			"horizontal",
+		);
+	});
+});

package/test/TabGroup/components/TabGroupAccessibility.torp

@@ -0,0 +1,28 @@
+import {
+	TabGroup,
+	TabList,
+	TabHeader,
+	TabTrigger,
+	TabContent,
+} from "../../../src/TabGroup/index";
+
+export default function TabGroupAccessibility() {
+	@render {
+		<TabGroup value={$props.value}>
+			<TabList ariaLabel="Example tabs">
+				<TabHeader as="h4">
+					<TabTrigger>Header 1</TabTrigger>
+				</TabHeader>
+				<TabHeader as="h4">
+					<TabTrigger>Header 2</TabTrigger>
+				</TabHeader>
+				<TabHeader as="h4">
+					<TabTrigger>Header 3</TabTrigger>
+				</TabHeader>
+			</TabList>
+			<TabContent>Body 1</TabContent>
+			<TabContent>Body 2</TabContent>
+			<TabContent>Body 3</TabContent>
+		</TabGroup>
+	}
+}

package/test/TabGroup/components/TabGroupKeyboard.torp

@@ -0,0 +1,28 @@
+import {
+	TabGroup,
+	TabList,
+	TabHeader,
+	TabTrigger,
+	TabContent,
+} from "../../../src/TabGroup/index";
+
+export default function TabGroupKeyboard() {
+	@render {
+		<TabGroup value={$props.value}>
+			<TabList>
+				<TabHeader as="h4">
+					<TabTrigger>Header 1</TabTrigger>
+				</TabHeader>
+				<TabHeader as="h4">
+					<TabTrigger>Header 2</TabTrigger>
+				</TabHeader>
+				<TabHeader as="h4">
+					<TabTrigger>Header 3</TabTrigger>
+				</TabHeader>
+			</TabList>
+			<TabContent>Content 1</TabContent>
+			<TabContent>Content 2</TabContent>
+			<TabContent>Content 3</TabContent>
+		</TabGroup>
+	}
+}

package/test/TabGroup/components/TabGroupList.torp

@@ -0,0 +1,26 @@
+import {
+	TabGroup,
+	TabList,
+	TabHeader,
+	TabTrigger,
+	TabContent,
+} from "../../../src/TabGroup/index";
+
+export default function TabGroupList() {
+	@render {
+		<TabGroup value={$props.value}>
+			<TabList>
+			@for (let item of $props.items) {
+				@key = item.id
+				<TabHeader as="h4">
+					<TabTrigger>{item.header}</TabTrigger>
+				</TabHeader>
+			}
+			</TabList>
+			@for (let item of $props.items) {
+				@key = item.id
+				<TabContent>{item.text}</TabContent>
+			}
+		</TabGroup>
+	}
+}