@torpor/ui 0.0.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@torpor/ui",
+  "version": "0.0.1",
+  "description": "Accessible, unstyled components for use in your Torpor front-end",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./Accordion": {
+      "types": "./dist/Accordion/index.d.ts",
+      "import": "./dist/Accordion/index.js",
+      "require": "./dist/Accordion/index.cjs"
+    },
+    "./motion": {
+      "types": "./dist/motion.d.ts",
+      "import": "./dist/motion.js",
+      "require": "./dist/motion.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/user-event": "^14.5.2",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.0",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^22.10.1",
+    "chalk": "^5.3.0",
+    "esno": "^4.8.0",
+    "fast-glob": "^3.3.2",
+    "jsdom": "^25.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "@torpor/unplugin": "^0.0.1",
+    "@torpor/view": "^0.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:fix": "esno scripts/postbuild.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/scripts/postbuild.ts

@@ -0,0 +1,62 @@
+import chalk from "chalk";
+import { existsSync, promises as fs, lstatSync } from "node:fs";
+import { 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");
+
+	// Loop through component folders e.g. Accordion
+	const componentFolders = (await fs.readdir(distFolder)).filter((f) =>
+		lstatSync(join(distFolder, f)).isDirectory(),
+	);
+	for (const component of componentFolders) {
+		console.log(chalk.cyan.inverse(" POST "), `Tidy ${component}`);
+
+		// Loop through files and change declarations to imports so they get
+		// processed by bundlers
+		let indexFiles = await fs.readdir(join(distFolder, component));
+		for (const file of indexFiles) {
+			let jsfile = join(distFolder, component, file);
+			let code = await fs.readFile(jsfile, "utf8");
+			code = code.replace(/var (.+?) = "\.\.\/(.+?)-(.+?).torp"/g, 'import $1 from "./$2.torp"');
+			await fs.writeFile(jsfile, code);
+		}
+
+		// 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) {
+			const newfile = file.substring(0, file.indexOf("-")) + ".torp";
+			await fs.rename(join(distFolder, file), join(distFolder, component, newfile));
+		}
+
+		// Move all *.ts files into this folder
+		const srcFolder = resolve(distFolder, "..", "src", component);
+		const tsFiles = (await fs.readdir(srcFolder)).filter(
+			(f) => f.endsWith(".ts") && f !== "index.ts",
+		);
+		for (const file of tsFiles) {
+			await fs.copyFile(join(srcFolder, file), join(distFolder, component, file));
+		}
+	}
+
+	// Move all utils/*.ts files into the dest folder
+	if (!existsSync(join(distFolder, "utils"))) {
+		await fs.mkdir(join(distFolder, "utils"));
+	}
+
+	const utilsFolder = resolve(distFolder, "..", "src", "utils");
+	const utilsFiles = (await fs.readdir(utilsFolder)).filter(
+		(f) => f.endsWith(".ts") && f !== "index.ts",
+	);
+	for (const file of utilsFiles) {
+		await fs.copyFile(join(utilsFolder, file), join(distFolder, "utils", file));
+	}
+}
+
+run();

package/src/Accordion/Accordion.torp

@@ -0,0 +1,208 @@
+import { AccordionContextName, type AccordionContext, type ItemState } from './AccordionTypes';
+
+/**
+ * A vertically stacked set of interactive headings that enable users to reveal
+ * or hide associated sections of content.
+ *
+ * See [the WAI ARIA guidelines for Accordions](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
+ *
+ * The structure of an Accordion is:
+ *
+ * ```
+ * <Accordion>
+ * 	<AccordionItem>
+ * 		<AccordionHeader>
+ * 			<AccordionTrigger />
+ * 		</AccordionHeader>
+ * 		<AccordionContent />
+ * 	</AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @prop {'single' | 'multiple'} type -- Whether a single AccordionItem or multiple AccordionItems can be expanded at the same time
+ * @prop {string | string[]} value -- The value of the expanded AccordionItem, or an array of values if the type is 'multiple'
+ * @prop {boolean} disabled -- If set to true, the user cannot interact with any items in the Accordion
+ * @prop {(value: string | string[]) => void} [onchange] -- Raised when the expanded item(s) have changed
+ */
+export default function ($props: any) {
+	$props.type ||= 'single';
+	$props.value ||= $props.type === 'single' ? '' : [];
+
+	interface State {
+		value: string | string[];
+		itemStates: ItemState[];
+	}
+
+	let $state: State = $watch({
+		value: $props.value,
+		itemStates: []
+	})
+
+	// This is used to assign automatic indexes to items where needed
+	let nextIndex = 0;
+
+	// Set the context to pass down to items, with functions for each item to call
+	let context: AccordionContext = {
+		registerItem,
+		removeItem,
+		toggleItem,
+		handleHeaderKey
+	};
+	$context[AccordionContextName] = context;
+
+	$run(() => {
+		// HACK: This should probably be done with setters?
+		let newValue = $state.value;
+
+		// Get the value
+		switch ($props.type) {
+			case 'single': {
+				// 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.expanded = item.value === newValue;
+				}
+				break;
+			}
+			case 'multiple': {
+				// Ensure the value passed in is an array
+				if (!Array.isArray(newValue)) {
+					newValue = [newValue];
+				}
+				for (let item of $state.itemStates) {
+					item.expanded = newValue.indexOf(item.value) !== -1;
+				}
+				break;
+			}
+		}
+
+		// 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);
+		}
+	})
+
+	function registerItem(itemState: ItemState) {
+		// If an index wasn't set for the item, set it automatically
+		if (itemState.index === -1) {
+			itemState.index = nextIndex++;
+		}
+
+		// If a value wasn't set for the item, set it to the index
+		if (!itemState.value) {
+			itemState.value = itemState.index.toString();
+		}
+
+		// If we have a value, set whether the item should be expanded
+		if ($state.value) {
+			switch ($props.type) {
+				case 'single': {
+					itemState.expanded = $state.value === itemState.value;
+					break;
+				}
+				case 'multiple': {
+					itemState.expanded = $state.value.includes(itemState.value);
+					break;
+				}
+			}
+		}
+
+		// Set whether the Accordion itself is disabled
+		$state.parentDisabled = $props.disabled
+
+		// Add the item's state to the array
+		$state.itemStates.splice(itemState.index, 0, itemState);
+	}
+
+	// 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 toggleItem(toggleValue: string) {
+		switch ($props.type) {
+			case 'single': {
+				for (let item of $state.itemStates) {
+					// The item is expanded if it has the supplied value (i.e. if it was clicked) and if it
+					// wasn't already expanded (i.e. we collapse it if it was expanded and clicked)
+					if (item.value === toggleValue) {
+						$state.value = item.expanded ? '' : item.value;
+						break;
+					}
+				}
+				break;
+			}
+			case 'multiple': {
+				let newValue = [];
+				for (let item of $state.itemStates) {
+					// The item is expanded if it has the supplied value (i.e. if it was clicked) or if it
+					// was already expanded
+					if (
+						(item.value === toggleValue && !item.expanded) ||
+						(item.value !== toggleValue && item.expanded)
+					) {
+						newValue.push(item.value);
+					}
+				}
+				$state.value = newValue.sort();
+				break;
+			}
+		}
+	}
+
+	function handleHeaderKey(headerIndex: number, e: KeyboardEvent) {
+		switch (e.key) {
+			case 'Up':
+			case 'ArrowUp': {
+				if (headerIndex > 0) {
+					e.preventDefault();
+					$state.itemStates[headerIndex - 1].setFocused();
+				}
+				break;
+			}
+			case 'Down':
+			case 'ArrowDown': {
+				if (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-accordion">
+			<:slot />
+		</div>
+	}
+}

package/src/Accordion/AccordionContent.torp

@@ -0,0 +1,36 @@
+import getId from '../utils/getId';
+import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+
+/**
+ * Content for an AccordionItem, which can be revealed or hidden by an associated AccordionTrigger.
+ *
+ * @prop {string} [id] -- An ID for the AccordionContent's div container
+ * @prop {boolean} [ariaRegion] -- Whether this content should act as a region. Set this when the content contains heading elements or a nested Accordion
+ */
+export default function AccordionContent($props: any) {
+	$props.id ||= getId();
+
+	const context = $context[AccordionItemContextName] as AccordionItemContext;
+	if (!context) {
+		throw new Error('AccordionContent must be contained within an AccordionItem');
+	}
+	let $state = $context[AccordionItemContextName].state
+
+	// Set the content ID so that it can be used with aria-controls in AccordionTrigger
+	$state.contentId = $props.id;
+
+	@render {
+		<div
+			id={$props.id}
+			class='torp-accordion-content'
+			role={$props.ariaRegion ? 'region' : undefined}
+			aria-labelledby={$state.headerId}
+			data-state={$state.dataState}
+			data-disabled={$state.dataDisabled}
+		>
+			@if ($state.expanded) {
+				<:slot />
+			}
+		</div>
+	}
+}

package/src/Accordion/AccordionHeader.torp

@@ -0,0 +1,33 @@
+import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+
+/**
+ * The header for an AccordionItem, which contains the AccordionTrigger.
+ *
+ * The structure of an AccordionHeader is:
+ * 
+ * ```
+ * <AccordionHeader>
+ * 	<AccordionTrigger />
+ * </AccordionHeader>
+ * ```
+ *
+ * @prop {'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'} as -- The type of HTML header to use
+ */
+export default function ($props: any) {
+	const context = $context[AccordionItemContextName] as AccordionItemContext;
+	if (!context) {
+		throw new Error('AccordionHeader must be contained within an AccordionItem');
+	}
+	let $state = $context[AccordionItemContextName].state
+
+	@render {
+		@// TODO: $props.as
+		<h4
+			class='torp-accordion-header'
+			data-state={$state.dataState}
+			data-disabled={$state.dataDisabled}
+		>
+			<:slot />
+		</h4>
+	}
+}

package/src/Accordion/AccordionItem.torp

@@ -0,0 +1,75 @@
+import { AccordionContextName, AccordionItemContextName, type AccordionContext, type AccordionItemContext } from './AccordionTypes';
+
+/**
+ * An item in an Accordion, which must consist of an AccordionTrigger and an AccordionContent.
+ * 
+ * The structure of an AccordionItem is:
+ * 
+ * ```
+ * <AccordionItem>
+ * 	<AccordionHeader>
+ * 		<AccordionTrigger />
+ * 	</AccordionHeader>
+ * 	<AccordionContent />
+ * </AccordionItem>
+ * ```
+ *
+ * @prop {number} [index] -- The index of this item in the Accordion. Set this if you will be inserting, removing or sorting items. If you don't set this, it will be set automatically
+ * @prop {string} [value] -- A value for the item. Set this if you need more control over which item(s) are expanded. If you don't set this, the value will be set to the item's initial index
+ * @prop {boolean} [disabled] -- If set to true, the user cannot interact with this AccordionItem
+ * @prop {(boolean) => void} [ontoggle] -- Raised when this item is opened or closed
+ */
+export default function AccordionItem($props: any) {
+	let $state: ItemState = $watch({
+		index: -1,
+		value: "",
+		expanded: false,
+		disabled: $props.disabled,
+		parentDisabled: false,
+		get dataState() {
+			return this.expanded ? 'open' : 'closed';
+		},
+	})
+
+	// Get stuff out of the AccordionContext
+	const context = $context[AccordionContextName] as AccordionContext;
+	if (!context) {
+		throw new Error('AccordionItem must be contained within an Accordion');
+	}
+
+	// Put stuff into an AccordionItemContext
+	const itemContext: AccordionItemContext = {
+		toggleItem: context.toggleItem,
+		handleHeaderKey: context.handleHeaderKey,
+		state: $state,
+	};
+	$context[AccordionItemContextName] = itemContext;
+
+	// Register this item with the parent Accordion, which will handle toggling expanded for all items
+	context.registerItem($state);
+
+	// Remove the item from the parent Accordion when this item is destroyed
+	$run(() => {
+		return () => {
+			context.removeItem($state.index);
+		}
+	});
+
+	// Dispatch the toggle event when the value of expanded changes
+	// TODO: Should this be a setter instead?
+	$run(() => {
+		if ($props.ontoggle) {
+			$props.ontoggle($state.expanded);
+		}
+	})
+
+	@render {
+		<div
+			class='torp-accordion-item'
+			data-state={$state.dataState}
+			data-disabled={$state.dataDisabled}
+		>
+			<:slot />
+		</div>
+	}
+}

package/src/Accordion/AccordionTrigger.torp

@@ -0,0 +1,59 @@
+import getId from '../utils/getId';
+import { AccordionItemContextName, type AccordionItemContext } from './AccordionTypes';
+
+/**
+ * A header button for an AccordionItem, which can be used to reveal or hide an associated AccordionContent.
+ */
+export default function AccordionTrigger() {
+	let button: HTMLButtonElement;
+
+	$props.id ||= getId();
+
+	// Get stuff out of the AccordionItemContext
+	const context = $context[AccordionItemContextName] as AccordionItemContext;
+	if (!context) {
+		throw new Error('AccordionTrigger must be contained within an AccordionItem');
+	}
+	let $state = $context[AccordionItemContextName].state;
+
+	// Set the header ID so that it can be used with aria-labelledby in AccordionContent
+	$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 Accordion to focus this item's button
+	function setFocused() {
+		button.focus();
+	}
+
+	function handleClick() {
+		// Pass the value to the toggleItem method in the parent Accordion which will handle toggling
+		// the value of expanded for all items (e.g. to close other items if necessary)
+		context.toggleItem($state.value);
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		// Pass the key press up to the parent Accordion which will handle setting the focused button
+		context.handleHeaderKey($state.index, e);
+	}
+
+	@render {
+		<button
+			type="button"
+			id={$props.id}
+			class='torp-accordion-button'
+			disabled={$state.disabled || $state.parentDisabled}
+			aria-expanded={$state.expanded.toString()}
+			aria-disabled={$state.disabled}
+			aria-controls={$state.contentId}
+			data-state={$state.dataState}
+			data-disabled={$state.disabled}
+			:self={button}
+			onclick={handleClick}
+			onkeydown={handleKey}
+		>
+			<:slot />
+		</button>
+	}
+}

package/src/Accordion/AccordionTypes.ts

@@ -0,0 +1,32 @@
+export const AccordionContextName = "Accordion";
+export const AccordionItemContextName = "AccordionItem";
+
+export interface AccordionContext {
+	/** Called from an AccordionItem when it is added */
+	registerItem: (state: ItemState, setFocused: () => void) => void;
+	/** Called from an AccordionItem when it is removed */
+	removeItem: (index: number) => void;
+	/** Called from an AccordionItem when it is toggled */
+	toggleItem: (value: string) => void;
+	/** Called from an AccordionHeader when it receives a keyboard event */
+	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
+}
+
+export interface AccordionItemContext {
+	/** Called when an AccordionItem is toggled */
+	toggleItem: (value: string) => void;
+	/** Called when an AccordionHeader receives a keyboard event */
+	handleHeaderKey: (index: number, e: KeyboardEvent) => void;
+	/** The reactive state for an AccordionItem */
+	state: ItemState;
+}
+
+export interface ItemState {
+	index: number;
+	value: string;
+	expanded: boolean;
+	disabled: boolean;
+	parentDisabled: boolean;
+	/** Called in the Accordion when a header needs to be focused */
+	setFocused: () => void;
+}

package/src/Accordion/index.ts

@@ -0,0 +1,7 @@
+import Accordion from "./Accordion.torp";
+import AccordionContent from "./AccordionContent.torp";
+import AccordionHeader from "./AccordionHeader.torp";
+import AccordionItem from "./AccordionItem.torp";
+import AccordionTrigger from "./AccordionTrigger.torp";
+
+export { Accordion, AccordionItem, AccordionHeader, AccordionTrigger, AccordionContent };

package/src/Accordion.ts

@@ -0,0 +1,7 @@
+import Accordion from "./Accordion/Accordion.torp";
+import AccordionContent from "./Accordion/AccordionContent.torp";
+import AccordionHeader from "./Accordion/AccordionHeader.torp";
+import AccordionItem from "./Accordion/AccordionItem.torp";
+import AccordionTrigger from "./Accordion/AccordionTrigger.torp";
+
+export { Accordion, AccordionItem, AccordionHeader, AccordionTrigger, AccordionContent };

package/src/motion/fade.ts

@@ -0,0 +1,2 @@
+const animationFrames = [{ opacity: 0 }, { opacity: 1 }];
+export default animationFrames;

package/src/motion.ts

@@ -0,0 +1,3 @@
+import fade from "./motion/fade";
+
+export { fade };

package/src/utils/getId.ts

@@ -0,0 +1,6 @@
+let nextId = 0;
+
+/** Returns a unique ID for use by components that need one, e.g. for accessibility */
+export default function getId(): string {
+	return `torp-id-${nextId++}`;
+}

package/test/Accordion/accessibility.test.ts

@@ -0,0 +1,62 @@
+import { queryByText } from "@testing-library/dom";
+import "@testing-library/jest-dom/vitest";
+import userEvent from "@testing-library/user-event";
+import { mount } from "@torpor/view";
+import { describe, expect, it } from "vitest";
+import AccordionAccessibility from "./components/AccordionAccessibility.torp";
+
+describe("Accordion", () => {
+	it("Accessibility", async () => {
+		const user = userEvent.setup();
+
+		const container = document.createElement("div");
+		document.body.appendChild(container);
+		mount(container, AccordionAccessibility, { value: ["1", "3"] });
+
+		// Tests from https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+
+		// The title of each accordion header is contained in an element with role button
+		expect(queryByText(container, "Role Header")?.tagName.toLowerCase()).toMatch("button");
+
+		// Each accordion header button is wrapped in an element with role heading that has a value set
+		// for aria-level that is appropriate for the information architecture of the page
+		//   * If the native host language has an element with an implicit heading and aria-level, such
+		//     as an HTML heading tag, a native host language element may be used
+		//   * The button element is the only element inside the heading element. That is, if there are
+		//     other visually persistent elements, they are not included inside the heading element
+		// NOTE: This is kind of up to the user -- should we check this at runtime?
+		expect(queryByText(container, "Role Header")?.parentElement?.tagName.toLowerCase()).toMatch(
+			"h4",
+		);
+		expect(
+			queryByText(container, "Role Header")?.parentElement?.childElementCount.toString(),
+		).toMatch("1");
+
+		// If the accordion panel associated with an accordion header is visible, the header button
+		// element has aria-expanded set to true. If the panel is not visible, aria-expanded is set
+		// to false
+		expect(queryByText(container, "Open Header")).toHaveAttribute("aria-expanded", "true");
+		expect(queryByText(container, "Closed Header")).toHaveAttribute("aria-expanded", "false");
+
+		// The accordion header button element has aria-controls set to the ID of the element containing
+		// the accordion panel content
+		const headerId = queryByText(container, "Open Header")?.id;
+		const contentId = queryByText(container, "Open Content")?.id;
+		expect(queryByText(container, "Open Header")).toHaveAttribute("aria-controls", contentId);
+
+		// If the accordion panel associated with an accordion header is visible, and if the accordion
+		// does not permit the panel to be collapsed, the header button element has aria-disabled set
+		// to true
+		expect(queryByText(container, "Disabled Header")).toHaveAttribute("aria-disabled", "true");
+
+		// Optionally, each element that serves as a container for panel content has role region and
+		// aria-labelledby with a value that refers to the button that controls display of the panel
+		//   * Avoid using the region role in circumstances that create landmark region proliferation,
+		//     e.g., in an accordion that contains more than approximately 6 panels that can be expanded
+		//     at the same time
+		//   * Role region is especially helpful to the perception of structure by screen reader users
+		//     when panels contain heading elements or a nested accordion
+		expect(queryByText(container, "Open Content")).toHaveAttribute("aria-labelledby", headerId);
+		expect(queryByText(container, "Region Content")).toHaveAttribute("role", "region");
+	});
+});