@bug-on/md3-react 2.0.3 → 3.0.0

package/src/test/typography.test.tsx

@@ -0,0 +1,206 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+	MD3_EXPRESSIVE_FONT_VARIATION,
+	Typography,
+	TypographyKeyTokens,
+	TypographyProvider,
+	TypographyTokens,
+	useTypography,
+} from "../ui/typography";
+
+// ─── TypographyTokens ─────────────────────────────────────────────────────────
+
+describe("TypographyTokens", () => {
+	it("creates 30 styles (15 baseline + 15 emphasized)", () => {
+		const tokens = new TypographyTokens();
+		const baseline = [
+			"BodyLarge",
+			"BodyMedium",
+			"BodySmall",
+			"DisplayLarge",
+			"DisplayMedium",
+			"DisplaySmall",
+			"HeadlineLarge",
+			"HeadlineMedium",
+			"HeadlineSmall",
+			"LabelLarge",
+			"LabelMedium",
+			"LabelSmall",
+			"TitleLarge",
+			"TitleMedium",
+			"TitleSmall",
+		] as const;
+		const emphasized = baseline.map((k) => `${k}Emphasized` as const);
+
+		for (const key of baseline) {
+			expect(tokens[key]).toBeDefined();
+		}
+		for (const key of emphasized) {
+			expect((tokens as unknown as Record<string, unknown>)[key]).toBeDefined();
+		}
+	});
+
+	it("applies ROND 100 fontVariationSettings to all styles", () => {
+		const tokens = new TypographyTokens();
+		const styles = [
+			tokens.BodyLarge,
+			tokens.DisplayLarge,
+			tokens.HeadlineMedium,
+			tokens.LabelSmall,
+			tokens.TitleMedium,
+			tokens.BodyLargeEmphasized,
+			tokens.DisplayLargeEmphasized,
+			tokens.LabelSmallEmphasized,
+		];
+
+		for (const style of styles) {
+			expect(style.fontVariationSettings).toBe(MD3_EXPRESSIVE_FONT_VARIATION);
+			expect(style.fontVariationSettings).toBe('"ROND" 100');
+		}
+	});
+
+	it("uses Google Sans Flex as default font family", () => {
+		const tokens = new TypographyTokens();
+		expect(tokens.BodyLarge.fontFamily).toContain("Google Sans Flex");
+		expect(tokens.DisplayLarge.fontFamily).toContain("Google Sans Flex");
+	});
+
+	it("overrides font family when provided", () => {
+		const customFont = "'Inter', sans-serif";
+		const tokens = new TypographyTokens(customFont);
+		expect(tokens.BodyLarge.fontFamily).toBe(customFont);
+		expect(tokens.DisplayLargeEmphasized.fontFamily).toBe(customFont);
+	});
+
+	it("emphasized styles have higher fontWeight than baseline", () => {
+		const tokens = new TypographyTokens();
+		expect(tokens.BodyLargeEmphasized.fontWeight).toBeGreaterThan(
+			tokens.BodyLarge.fontWeight,
+		);
+		expect(tokens.DisplayLargeEmphasized.fontWeight).toBeGreaterThan(
+			tokens.DisplayLarge.fontWeight,
+		);
+		expect(tokens.LabelLargeEmphasized.fontWeight).toBeGreaterThan(
+			tokens.LabelLarge.fontWeight,
+		);
+	});
+
+	it("styles are frozen (immutable)", () => {
+		const tokens = new TypographyTokens();
+		expect(Object.isFrozen(tokens.BodyLarge)).toBe(true);
+		expect(Object.isFrozen(tokens.DisplayLargeEmphasized)).toBe(true);
+	});
+});
+
+// ─── Typography class ─────────────────────────────────────────────────────────
+
+describe("Typography", () => {
+	it("constructs with default tokens", () => {
+		const typography = new Typography();
+		expect(typography.bodyLarge).toBeDefined();
+		expect(typography.displayLargeEmphasized).toBeDefined();
+	});
+
+	it("fromToken returns correct style for all 30 keys", () => {
+		const typography = new Typography();
+		const allKeys = Object.values(TypographyKeyTokens);
+		expect(allKeys).toHaveLength(30);
+
+		for (const key of allKeys) {
+			const style = typography.fromToken(key);
+			expect(style).toBeDefined();
+			expect(style.fontVariationSettings).toBe('"ROND" 100');
+		}
+	});
+
+	it("fromToken(BodyLarge) matches bodyLarge property", () => {
+		const typography = new Typography();
+		expect(typography.fromToken(TypographyKeyTokens.BodyLarge)).toBe(
+			typography.bodyLarge,
+		);
+	});
+
+	it("fromToken(DisplayLargeEmphasized) matches displayLargeEmphasized property", () => {
+		const typography = new Typography();
+		expect(
+			typography.fromToken(TypographyKeyTokens.DisplayLargeEmphasized),
+		).toBe(typography.displayLargeEmphasized);
+	});
+
+	it("copy() creates a new instance with overridden styles", () => {
+		const original = new Typography();
+		const customStyle = { ...original.bodyLarge, fontWeight: 900 };
+		const modified = original.copy({ bodyLarge: customStyle });
+
+		expect(modified.bodyLarge.fontWeight).toBe(900);
+		expect(modified.displayLarge).toBe(original.displayLarge);
+	});
+});
+
+// ─── useTypography + TypographyProvider ───────────────────────────────────────
+
+function TestConsumer() {
+	const typography = useTypography();
+	return (
+		<div>
+			<span data-testid="font-size">{typography.bodyLarge.fontSize}</span>
+			<span data-testid="font-weight">
+				{typography.displayLargeEmphasized.fontWeight}
+			</span>
+			<span data-testid="variation">
+				{typography.bodyMedium.fontVariationSettings}
+			</span>
+		</div>
+	);
+}
+
+describe("useTypography", () => {
+	it("returns default Typography when no Provider is present", () => {
+		render(<TestConsumer />);
+		expect(screen.getByTestId("font-size").textContent).toBeTruthy();
+		expect(screen.getByTestId("variation").textContent).toBe('"ROND" 100');
+	});
+
+	it("returns Typography from TypographyProvider", () => {
+		render(
+			<TypographyProvider>
+				<TestConsumer />
+			</TypographyProvider>,
+		);
+		expect(screen.getByTestId("font-size").textContent).toBeTruthy();
+		expect(screen.getByTestId("variation").textContent).toBe('"ROND" 100');
+	});
+
+	it("allows custom fontFamily via TypographyProvider", () => {
+		function CustomConsumer() {
+			const typography = useTypography();
+			return (
+				<span data-testid="custom-family">
+					{typography.bodyLarge.fontFamily}
+				</span>
+			);
+		}
+
+		render(
+			<TypographyProvider fontFamily="'Inter', sans-serif">
+				<CustomConsumer />
+			</TypographyProvider>,
+		);
+		expect(screen.getByTestId("custom-family").textContent).toBe(
+			"'Inter', sans-serif",
+		);
+	});
+
+	it("emphasized fontWeight is higher than baseline", () => {
+		render(
+			<TypographyProvider>
+				<TestConsumer />
+			</TypographyProvider>,
+		);
+		const emphasizedWeight = Number(
+			screen.getByTestId("font-weight").textContent,
+		);
+		expect(emphasizedWeight).toBeGreaterThanOrEqual(700);
+	});
+});

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export type {
+	MD3ColorStyle,
+	MD3Shape,
+	MD3Size,
+	PolymorphicProps,
+	PolymorphicRef,
+} from "./md3";

package/src/types/md3.ts

@@ -0,0 +1,31 @@
+import type {
+	ComponentPropsWithoutRef,
+	ComponentPropsWithRef,
+	ElementType,
+	ReactNode,
+} from "react";
+
+/** MD3 button color variants */
+export type MD3ColorStyle =
+	| "elevated"
+	| "filled"
+	| "tonal"
+	| "outlined"
+	| "text";
+
+/** MD3 Expressive button sizes */
+export type MD3Size = "xs" | "sm" | "md" | "lg" | "xl";
+
+/** MD3 shape families */
+export type MD3Shape = "round" | "square";
+
+/** Helper: PolyMorphic component ref */
+export type PolymorphicRef<C extends ElementType> =
+	ComponentPropsWithRef<C>["ref"];
+
+/** Helper: Props cho polymorphic components */
+export type PolymorphicProps<C extends ElementType, Props = object> = Props &
+	Omit<ComponentPropsWithoutRef<C>, keyof Props> & {
+		as?: C;
+		children?: ReactNode;
+	};

package/src/ui/Text.tsx

@@ -0,0 +1,60 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+const typographyVariants = cva("m-0 p-0 text-m3-on-surface", {
+	variants: {
+		variant: {
+			"display-lg": "text-[57px] leading-[64px] font-normal tracking-[-0.25px]",
+			"display-md": "text-[45px] leading-[52px] font-normal tracking-[0px]",
+			"display-sm": "text-[36px] leading-[44px] font-normal tracking-[0px]",
+			"headline-lg": "text-[32px] leading-[40px] font-normal tracking-[0px]",
+			"headline-md": "text-[28px] leading-[36px] font-normal tracking-[0px]",
+			"headline-sm": "text-[24px] leading-[32px] font-normal tracking-[0px]",
+			"title-lg": "text-[22px] leading-[28px] font-normal tracking-[0px]",
+			"title-md": "text-[16px] leading-[24px] font-medium tracking-[0.15px]",
+			"title-sm": "text-[14px] leading-[20px] font-medium tracking-[0.1px]",
+			"label-lg": "text-[14px] leading-[20px] font-medium tracking-[0.1px]",
+			"label-md": "text-[12px] leading-[16px] font-medium tracking-[0.5px]",
+			"label-sm": "text-[11px] leading-[16px] font-medium tracking-[0.5px]",
+			"body-lg": "text-[16px] leading-[24px] font-normal tracking-[0.5px]",
+			"body-md": "text-[14px] leading-[20px] font-normal tracking-[0.25px]",
+			"body-sm": "text-[12px] leading-[16px] font-normal tracking-[0.4px]",
+		},
+	},
+	defaultVariants: {
+		variant: "body-md",
+	},
+});
+
+export interface TextProps
+	extends React.HTMLAttributes<HTMLElement>,
+		VariantProps<typeof typographyVariants> {
+	as?: React.ElementType;
+}
+
+const Text = React.forwardRef<HTMLElement, TextProps>(
+	({ className, variant, as: Component, ...props }, ref) => {
+		// Default component based on variant if not provided
+		const defaultComponent = React.useMemo(() => {
+			if (variant?.startsWith("display") || variant?.startsWith("headline"))
+				return "h1";
+			if (variant?.startsWith("title")) return "h2";
+			return "p";
+		}, [variant]);
+
+		const Tag = Component || defaultComponent;
+
+		return (
+			<Tag
+				ref={ref}
+				className={cn(typographyVariants({ variant, className }))}
+				{...props}
+			/>
+		);
+	},
+);
+
+Text.displayName = "Text";
+
+export { Text, typographyVariants };

package/src/ui/__snapshots__/divider.test.tsx.snap

@@ -0,0 +1,63 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Divider > snapshots > flat/horizontal (default) 1`] = `
+<div
+  aria-orientation="horizontal"
+  class="block shrink-0 bg-m3-outline-variant h-px w-full"
+  role="separator"
+  style="transform-origin: left; transform: scaleX(0);"
+/>
+`;
+
+exports[`Divider > snapshots > flat/vertical 1`] = `
+<div
+  aria-orientation="vertical"
+  class="block shrink-0 bg-m3-outline-variant w-px h-full self-stretch"
+  role="separator"
+  style="transform-origin: top; transform: scaleY(0);"
+/>
+`;
+
+exports[`Divider > snapshots > inset 1`] = `
+<div
+  aria-orientation="horizontal"
+  class="block shrink-0 bg-m3-outline-variant h-px w-full ml-4"
+  role="separator"
+  style="transform-origin: left; transform: scaleX(0);"
+/>
+`;
+
+exports[`Divider > snapshots > middle-inset 1`] = `
+<div
+  aria-orientation="horizontal"
+  class="block shrink-0 bg-m3-outline-variant h-px w-full mx-4"
+  role="separator"
+  style="transform-origin: left; transform: scaleX(0);"
+/>
+`;
+
+exports[`Divider > snapshots > wavy 1`] = `
+<div
+  aria-orientation="horizontal"
+  class="block shrink-0 overflow-hidden w-full"
+  role="separator"
+  style="height: 5px;"
+>
+  <svg
+    aria-hidden="true"
+    class="text-m3-outline-variant block"
+    height="100%"
+    style="overflow: visible; transform-origin: left center; opacity: 0; transform: scaleX(0);"
+    width="100%"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M 0.5,2.5 C 5.833333333333333,-0.16666666666666652 11.166666666666668,-0.16666666666666652 16.5,2.5 C 21.833333333333332,5.166666666666666 27.166666666666668,5.166666666666666 32.5,2.5 C 37.833333333333336,-0.16666666666666652 43.166666666666664,-0.16666666666666652 48.5,2.5 C 53.833333333333336,5.166666666666666 59.166666666666664,5.166666666666666 64.5,2.5 C 69.83333333333333,-0.16666666666666652 75.16666666666667,-0.16666666666666652 80.5,2.5 C 85.83333333333333,5.166666666666666 91.16666666666667,5.166666666666666 96.5,2.5 C 101.83333333333333,-0.16666666666666652 107.16666666666667,-0.16666666666666652 112.5,2.5 C 117.83333333333333,5.166666666666666 123.16666666666667,5.166666666666666 128.5,2.5 C 133.83333333333334,-0.16666666666666652 139.16666666666666,-0.16666666666666652 144.5,2.5 C 149.83333333333334,5.166666666666666 155.16666666666666,5.166666666666666 160.5,2.5 C 165.83333333333334,-0.16666666666666652 171.16666666666666,-0.16666666666666652 176.5,2.5 C 181.83333333333334,5.166666666666666 187.16666666666666,5.166666666666666 192.5,2.5 C 197.83333333333334,-0.16666666666666652 203.16666666666666,-0.16666666666666652 208.5,2.5 C 213.83333333333334,5.166666666666666 219.16666666666666,5.166666666666666 224.5,2.5 C 229.83333333333334,-0.16666666666666652 235.16666666666666,-0.16666666666666652 240.5,2.5 C 245.83333333333334,5.166666666666666 251.16666666666666,5.166666666666666 256.5,2.5 C 261.8333333333333,-0.16666666666666652 267.1666666666667,-0.16666666666666652 272.5,2.5 C 277.8333333333333,5.166666666666666 283.1666666666667,5.166666666666666 288.5,2.5 C 293.8333333333333,-0.16666666666666652 299.1666666666667,-0.16666666666666652 304.5,2.5 C 309.8333333333333,5.166666666666666 315.1666666666667,5.166666666666666 320.5,2.5 C 325.8333333333333,-0.16666666666666652 331.1666666666667,-0.16666666666666652 336.5,2.5 C 341.8333333333333,5.166666666666666 347.1666666666667,5.166666666666666 352.5,2.5 C 357.8333333333333,-0.16666666666666652 363.1666666666667,-0.16666666666666652 368.5,2.5 C 373.8333333333333,5.166666666666666 379.1666666666667,5.166666666666666 384.5,2.5 C 389.8333333333333,-0.16666666666666652 395.1666666666667,-0.16666666666666652 400.5,2.5 C 405.8333333333333,5.166666666666666 411.1666666666667,5.166666666666666 416.5,2.5 C 421.8333333333333,-0.16666666666666652 427.1666666666667,-0.16666666666666652 432.5,2.5 C 437.8333333333333,5.166666666666666 443.1666666666667,5.166666666666666 448.5,2.5 C 453.8333333333333,-0.16666666666666652 459.1666666666667,-0.16666666666666652 464.5,2.5 C 469.8333333333333,5.166666666666666 475.1666666666667,5.166666666666666 480.5,2.5 C 485.8333333333333,-0.16666666666666652 491.1666666666667,-0.16666666666666652 496.5,2.5 C 501.8333333333333,5.166666666666666 507.1666666666667,5.166666666666666 512.5,2.5 C 517.8333333333334,-0.16666666666666652 523.1666666666666,-0.16666666666666652 528.5,2.5 C 533.8333333333334,5.166666666666666 539.1666666666666,5.166666666666666 544.5,2.5 C 549.8333333333334,-0.16666666666666652 555.1666666666666,-0.16666666666666652 560.5,2.5 C 565.8333333333334,5.166666666666666 571.1666666666666,5.166666666666666 576.5,2.5 C 581.8333333333334,-0.16666666666666652 587.1666666666666,-0.16666666666666652 592.5,2.5 C 597.8333333333334,5.166666666666666 603.1666666666666,5.166666666666666 608.5,2.5 C 613.8333333333334,-0.16666666666666652 619.1666666666666,-0.16666666666666652 624.5,2.5 C 629.8333333333334,5.166666666666666 635.1666666666666,5.166666666666666 640.5,2.5 C 645.8333333333334,-0.16666666666666652 651.1666666666666,-0.16666666666666652 656.5,2.5 C 661.8333333333334,5.166666666666666 667.1666666666666,5.166666666666666 672.5,2.5 C 677.8333333333334,-0.16666666666666652 683.1666666666666,-0.16666666666666652 688.5,2.5 C 693.8333333333334,5.166666666666666 699.1666666666666,5.166666666666666 704.5,2.5 C 709.8333333333334,-0.16666666666666652 715.1666666666666,-0.16666666666666652 720.5,2.5 C 725.8333333333334,5.166666666666666 731.1666666666666,5.166666666666666 736.5,2.5 C 741.8333333333334,-0.16666666666666652 747.1666666666666,-0.16666666666666652 752.5,2.5 C 757.8333333333334,5.166666666666666 763.1666666666666,5.166666666666666 768.5,2.5 C 773.8333333333334,-0.16666666666666652 779.1666666666666,-0.16666666666666652 784.5,2.5 C 789.8333333333334,5.166666666666666 795.1666666666666,5.166666666666666 800.5,2.5 C 805.8333333333334,-0.16666666666666652 811.1666666666666,-0.16666666666666652 816.5,2.5 C 821.8333333333334,5.166666666666666 827.1666666666666,5.166666666666666 832.5,2.5 C 837.8333333333334,-0.16666666666666652 843.1666666666666,-0.16666666666666652 848.5,2.5 C 853.8333333333334,5.166666666666666 859.1666666666666,5.166666666666666 864.5,2.5 C 869.8333333333334,-0.16666666666666652 875.1666666666666,-0.16666666666666652 880.5,2.5 C 885.8333333333334,5.166666666666666 891.1666666666666,5.166666666666666 896.5,2.5 C 901.8333333333334,-0.16666666666666652 907.1666666666666,-0.16666666666666652 912.5,2.5 C 917.8333333333334,5.166666666666666 923.1666666666666,5.166666666666666 928.5,2.5 C 933.8333333333334,-0.16666666666666652 939.1666666666666,-0.16666666666666652 944.5,2.5 C 949.8333333333334,5.166666666666666 955.1666666666666,5.166666666666666 960.5,2.5 C 965.8333333333334,-0.16666666666666652 971.1666666666666,-0.16666666666666652 976.5,2.5 C 981.8333333333334,5.166666666666666 987.1666666666666,5.166666666666666 992.5,2.5 C 994.8333333333334,-0.16666666666666652 997.1666666666666,-0.16666666666666652 999.5,2.5"
+      fill="none"
+      stroke="currentColor"
+      stroke-linecap="round"
+      stroke-width="1"
+    />
+  </svg>
+</div>
+`;

package/src/ui/app-bar/app-bar-column.tsx

@@ -0,0 +1,99 @@
+/**
+ * @file app-bar-column.tsx
+ * MD3 Expressive App Bar Column DSL.
+ *
+ * Displays App Bar action items in a vertical column.
+ * Overflow items collapse into a dropdown menu.
+ *
+ * @see docs/m3/app-bars/AppBarColumn.kt
+ */
+
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { AppBarTokens } from "./app-bar.tokens";
+import type { AppBarColumnProps } from "./app-bar.types";
+import { AppBarItemButton } from "./app-bar-item-button";
+import { AppBarOverflowIndicator } from "./app-bar-overflow-indicator";
+
+/**
+ * MD3 Expressive App Bar Column.
+ *
+ * Renders action items in a vertical column. Commonly used in
+ * side navigation or rail-style App Bars.
+ *
+ * @example
+ * ```tsx
+ * <AppBarColumn
+ *   maxItemCount={3}
+ *   items={[
+ *     { type: 'clickable', icon: <Icon>edit</Icon>, label: 'Edit', onClick: handleEdit },
+ *     { type: 'clickable', icon: <Icon>delete</Icon>, label: 'Delete', onClick: handleDelete },
+ *   ]}
+ * />
+ * ```
+ */
+export function AppBarColumn({
+	items,
+	maxItemCount,
+	className,
+}: AppBarColumnProps) {
+	const containerRef = React.useRef<HTMLDivElement>(null);
+	const [visibleCount, setVisibleCount] = React.useState(
+		maxItemCount ?? items.length,
+	);
+
+	React.useEffect(() => {
+		if (maxItemCount !== undefined) {
+			setVisibleCount(Math.min(maxItemCount, items.length));
+			return;
+		}
+
+		const container = containerRef.current;
+		if (!container) return;
+
+		let debounceTimer: ReturnType<typeof setTimeout>;
+
+		const observer = new ResizeObserver((entries) => {
+			clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(() => {
+				const entry = entries[0];
+				if (!entry) return;
+
+				const available = entry.contentRect.height;
+				const itemHeight = AppBarTokens.iconButtonTouchTarget;
+				const hasOverflow = items.length > Math.floor(available / itemHeight);
+				const reservedHeight = hasOverflow ? itemHeight : 0;
+				const count = Math.max(
+					0,
+					Math.floor((available - reservedHeight) / itemHeight),
+				);
+				setVisibleCount(Math.min(count, items.length));
+			}, 100);
+		});
+
+		observer.observe(container);
+		return () => {
+			clearTimeout(debounceTimer);
+			observer.disconnect();
+		};
+	}, [items.length, maxItemCount]);
+
+	const visibleItems = items.slice(0, visibleCount);
+	const overflowItems = items.slice(visibleCount);
+
+	return (
+		<div
+			ref={containerRef}
+			className={cn("flex flex-col items-center", className)}
+		>
+			{visibleItems.map((item, index) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: static list from props
+				<AppBarItemButton key={index} item={item} />
+			))}
+
+			{overflowItems.length > 0 && (
+				<AppBarOverflowIndicator items={overflowItems} />
+			)}
+		</div>
+	);
+}

package/src/ui/app-bar/app-bar-item-button.tsx

@@ -0,0 +1,71 @@
+/**
+ * @file app-bar-item-button.tsx
+ * Shared icon button renderer for AppBarRow and AppBarColumn items.
+ *
+ * Extracted from duplicate RowItem/ColumnItem implementations.
+ */
+
+import { cn } from "../../lib/utils";
+import { APP_BAR_COLORS, AppBarTokens } from "./app-bar.tokens";
+import type { AppBarItem } from "./app-bar.types";
+
+interface AppBarItemButtonProps {
+	item: AppBarItem;
+}
+
+/**
+ * Renders a single App Bar action item as an icon button.
+ * Handles clickable, toggleable, and custom item types.
+ */
+export function AppBarItemButton({ item }: AppBarItemButtonProps) {
+	const isDisabled = item.enabled === false;
+
+	if (item.type === "custom" && item.appBarContent) {
+		return <>{item.appBarContent}</>;
+	}
+
+	const buttonClassName = cn(
+		"flex items-center justify-center rounded-full",
+		"focus-visible:outline-none focus-visible:ring-2",
+		isDisabled && "opacity-38 pointer-events-none",
+	);
+
+	const buttonStyle = {
+		width: AppBarTokens.iconButtonTouchTarget,
+		height: AppBarTokens.iconButtonTouchTarget,
+	};
+
+	if (item.type === "toggleable") {
+		return (
+			<button
+				type="button"
+				className={buttonClassName}
+				style={{
+					...buttonStyle,
+					color: item.checked
+						? APP_BAR_COLORS.navigationIcon
+						: APP_BAR_COLORS.actionIcon,
+				}}
+				aria-label={item.label}
+				aria-pressed={item.checked}
+				disabled={isDisabled}
+				onClick={() => item.onCheckedChange?.(!item.checked)}
+			>
+				{item.icon}
+			</button>
+		);
+	}
+
+	return (
+		<button
+			type="button"
+			className={buttonClassName}
+			style={{ ...buttonStyle, color: APP_BAR_COLORS.actionIcon }}
+			aria-label={item.label}
+			disabled={isDisabled}
+			onClick={item.onClick}
+		>
+			{item.icon}
+		</button>
+	);
+}

package/src/ui/app-bar/app-bar-items.test.tsx

@@ -0,0 +1,89 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { AppBarItem } from "./app-bar.types";
+import { AppBarColumn } from "./app-bar-column";
+import { AppBarItemButton } from "./app-bar-item-button";
+import { AppBarRow } from "./app-bar-row";
+
+const mockItems: AppBarItem[] = [
+	{
+		type: "clickable",
+		icon: <span data-testid="icon-1">I1</span>,
+		label: "Action 1",
+		onClick: vi.fn(),
+	},
+	{
+		type: "toggleable",
+		icon: <span data-testid="icon-2">I2</span>,
+		label: "Action 2",
+		checked: false,
+		onCheckedChange: vi.fn(),
+	},
+	{
+		type: "custom",
+		icon: <span>I3</span>,
+		label: "Action 3",
+		appBarContent: <div data-testid="custom-item">Custom</div>,
+	},
+];
+
+describe("AppBar Items", () => {
+	describe("AppBarItemButton", () => {
+		it("renders clickable item and handles click", () => {
+			render(<AppBarItemButton item={mockItems[0]} />);
+			const btn = screen.getByLabelText("Action 1");
+			expect(btn).toBeInTheDocument();
+			fireEvent.click(btn);
+			expect(mockItems[0].onClick).toHaveBeenCalled();
+		});
+
+		it("renders toggleable item and handles toggle", () => {
+			render(<AppBarItemButton item={mockItems[1]} />);
+			const btn = screen.getByLabelText("Action 2");
+			expect(btn).toHaveAttribute("aria-pressed", "false");
+			fireEvent.click(btn);
+			expect(mockItems[1].onCheckedChange).toHaveBeenCalledWith(true);
+		});
+
+		it("renders custom item content", () => {
+			render(<AppBarItemButton item={mockItems[2]} />);
+			expect(screen.getByTestId("custom-item")).toBeInTheDocument();
+		});
+	});
+
+	describe("AppBarRow", () => {
+		it("renders all items when maxItemCount is sufficient", () => {
+			render(<AppBarRow items={mockItems} />);
+			expect(screen.getByLabelText("Action 1")).toBeInTheDocument();
+			expect(screen.getByLabelText("Action 2")).toBeInTheDocument();
+			expect(screen.getByTestId("custom-item")).toBeInTheDocument();
+		});
+
+		it("shows overflow indicator when items exceed maxItemCount", () => {
+			render(<AppBarRow items={mockItems} maxItemCount={2} />);
+			expect(screen.getByLabelText("Action 1")).toBeInTheDocument();
+			// Action 2 vs Action 3 depending on how maxItemCount slices. Usually shows first N-1 and the indicator.
+			// Let's just check for the More actions indicator
+			expect(
+				screen.getByRole("button", { name: "More actions" }),
+			).toBeInTheDocument();
+		});
+	});
+
+	describe("AppBarColumn", () => {
+		it("renders items vertically", () => {
+			render(<AppBarColumn items={mockItems} />);
+			expect(screen.getByLabelText("Action 1")).toBeInTheDocument();
+			expect(screen.getByLabelText("Action 2")).toBeInTheDocument();
+			expect(screen.getByTestId("custom-item")).toBeInTheDocument();
+		});
+
+		it("shows overflow indicator when items exceed maxItemCount", () => {
+			render(<AppBarColumn items={mockItems} maxItemCount={1} />);
+			expect(screen.getByLabelText("Action 1")).toBeInTheDocument(); // maybe Action 1 is replaced or first item is passed depending on n-1 rule
+			expect(
+				screen.getByRole("button", { name: "More actions" }),
+			).toBeInTheDocument();
+		});
+	});
+});