appos 0.4.3-0 → 0.5.1-0

package/src/web/ui/breadcrumb.stories.tsx

@@ -0,0 +1,271 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { IconHome, IconSlash } from "@tabler/icons-react";
+import { Link } from "react-router";
+import {
+	Breadcrumb,
+	BreadcrumbEllipsis,
+	BreadcrumbItem,
+	BreadcrumbLink,
+	BreadcrumbList,
+	BreadcrumbPage,
+	BreadcrumbSeparator,
+} from "#src/web/ui/breadcrumb.tsx";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from "#src/web/ui/dropdown-menu.tsx";
+
+const meta = {
+	title: "Base/Breadcrumb",
+	component: Breadcrumb,
+	tags: ["autodocs"],
+	parameters: {
+		layout: "centered",
+		docs: {
+			description: {
+				component:
+					"Displays the path to the current resource using a hierarchy of links. Helps users understand their location within the application and navigate back to parent pages.",
+			},
+		},
+	},
+} satisfies Meta<typeof Breadcrumb>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/">Home</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/products">Products</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbPage>Electronics</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Default breadcrumb navigation showing a hierarchy of pages. The current page uses BreadcrumbPage for styling.",
+			},
+		},
+	},
+};
+
+export const WithHomeIcon: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/">
+						<IconHome className="size-4" />
+					</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbPage>Settings</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Breadcrumb with a home icon instead of text for the root level.",
+			},
+		},
+	},
+};
+
+export const WithEllipsis: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/">Home</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbEllipsis />
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/products/electronics">
+						Electronics
+					</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbPage>Smartphones</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Breadcrumb with ellipsis to truncate long paths. Use when the hierarchy is too deep to display fully.",
+			},
+		},
+	},
+};
+
+export const WithDropdown: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/">Home</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<DropdownMenu>
+						<DropdownMenuTrigger className="flex items-center gap-1">
+							<BreadcrumbEllipsis />
+						</DropdownMenuTrigger>
+						<DropdownMenuContent align="start">
+							<DropdownMenuItem>Products</DropdownMenuItem>
+							<DropdownMenuItem>Categories</DropdownMenuItem>
+							<DropdownMenuItem>Electronics</DropdownMenuItem>
+						</DropdownMenuContent>
+					</DropdownMenu>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/products/electronics/phones">
+						Phones
+					</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbPage>iPhone 15</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Breadcrumb with a dropdown menu for collapsed items. Allows users to navigate to hidden intermediate pages.",
+			},
+		},
+	},
+};
+
+export const CustomSeparator: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/">Home</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator>
+					<IconSlash className="size-3.5" />
+				</BreadcrumbSeparator>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator>
+					<IconSlash className="size-3.5" />
+				</BreadcrumbSeparator>
+				<BreadcrumbItem>
+					<BreadcrumbPage>Components</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Breadcrumb with a custom separator icon. Pass a child to BreadcrumbSeparator to override the default chevron.",
+			},
+		},
+	},
+};
+
+export const WithRouterLink: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink render={<Link to="/" />}>Home</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink render={<Link to="/settings" />}>
+						Settings
+					</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbPage>Profile</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Breadcrumb with React Router Link components using the render prop for client-side navigation.",
+			},
+		},
+	},
+};
+
+export const LongPath: Story = {
+	render: () => (
+		<Breadcrumb>
+			<BreadcrumbList>
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/">Home</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/organization">Organization</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/organization/teams">Teams</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbLink href="/organization/teams/engineering">
+						Engineering
+					</BreadcrumbLink>
+				</BreadcrumbItem>
+				<BreadcrumbSeparator />
+				<BreadcrumbItem>
+					<BreadcrumbPage>Members</BreadcrumbPage>
+				</BreadcrumbItem>
+			</BreadcrumbList>
+		</Breadcrumb>
+	),
+	parameters: {
+		docs: {
+			description: {
+				story:
+					"Full breadcrumb path without truncation. Consider using ellipsis for very deep hierarchies.",
+			},
+		},
+	},
+};

package/src/web/ui/breadcrumb.tsx

@@ -0,0 +1,214 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { ChevronRightIcon, MoreHorizontalIcon } from "lucide-react";
+import type * as React from "react";
+import { cn } from "#src/web/lib/utils.ts";
+
+/**
+ * A navigation component that shows the user's current location in a hierarchy.
+ *
+ * Helps users understand their position within a site structure and navigate
+ * back to parent pages. Includes proper accessibility attributes.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Current Page</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ */
+function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
+	return (
+		<nav
+			aria-label="breadcrumb"
+			data-slot="breadcrumb"
+			className={cn(className)}
+			{...props}
+		/>
+	);
+}
+
+/**
+ * The ordered list container for breadcrumb items.
+ *
+ * Wraps BreadcrumbItem components and handles flex layout with proper spacing.
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbList>
+ *   <BreadcrumbItem>...</BreadcrumbItem>
+ * </BreadcrumbList>
+ * ```
+ */
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+	return (
+		<ol
+			data-slot="breadcrumb-list"
+			className={cn(
+				"text-muted-foreground gap-1.5 text-sm sm:gap-2.5 flex flex-wrap items-center wrap-break-word",
+				className,
+			)}
+			{...props}
+		/>
+	);
+}
+
+/**
+ * A single item in the breadcrumb navigation.
+ *
+ * Contains either a BreadcrumbLink for navigable items or BreadcrumbPage
+ * for the current page indicator.
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbItem>
+ *   <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+ * </BreadcrumbItem>
+ * ```
+ */
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+	return (
+		<li
+			data-slot="breadcrumb-item"
+			className={cn("gap-1.5 inline-flex items-center", className)}
+			{...props}
+		/>
+	);
+}
+
+/**
+ * A navigable link within a breadcrumb item.
+ *
+ * Use for all breadcrumb levels except the current page. Supports custom
+ * rendering via the `render` prop for integration with routing libraries.
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+ * ```
+ */
+function BreadcrumbLink({
+	className,
+	render,
+	...props
+}: useRender.ComponentProps<"a">) {
+	return useRender({
+		defaultTagName: "a",
+		props: mergeProps<"a">(
+			{
+				className: cn("hover:text-foreground transition-colors", className),
+			},
+			props,
+		),
+		render,
+		state: {
+			slot: "breadcrumb-link",
+		},
+	});
+}
+
+/**
+ * The current page indicator in a breadcrumb trail.
+ *
+ * Non-interactive element that represents the user's current location.
+ * Includes proper ARIA attributes for accessibility.
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbPage>Settings</BreadcrumbPage>
+ * ```
+ */
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+	return (
+		<span
+			data-slot="breadcrumb-page"
+			role="link"
+			aria-disabled="true"
+			aria-current="page"
+			className={cn("text-foreground font-normal", className)}
+			{...props}
+		/>
+	);
+}
+
+/**
+ * A visual separator between breadcrumb items.
+ *
+ * Displays a chevron icon by default but accepts custom children.
+ * Hidden from screen readers as it's purely decorative.
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbSeparator />
+ * <BreadcrumbSeparator>/</BreadcrumbSeparator>
+ * ```
+ */
+function BreadcrumbSeparator({
+	children,
+	className,
+	...props
+}: React.ComponentProps<"li">) {
+	return (
+		<li
+			data-slot="breadcrumb-separator"
+			role="presentation"
+			aria-hidden="true"
+			className={cn("[&>svg]:size-3.5", className)}
+			{...props}
+		>
+			{children ?? <ChevronRightIcon />}
+		</li>
+	);
+}
+
+/**
+ * An ellipsis indicator for truncated breadcrumb trails.
+ *
+ * Use when there are too many levels to display. Often combined with a
+ * dropdown menu to show hidden items.
+ *
+ * @example
+ * ```tsx
+ * <BreadcrumbItem>
+ *   <BreadcrumbEllipsis />
+ * </BreadcrumbItem>
+ * ```
+ */
+function BreadcrumbEllipsis({
+	className,
+	...props
+}: React.ComponentProps<"span">) {
+	return (
+		<span
+			data-slot="breadcrumb-ellipsis"
+			role="presentation"
+			aria-hidden="true"
+			className={cn(
+				"size-5 [&>svg]:size-4 flex items-center justify-center",
+				className,
+			)}
+			{...props}
+		>
+			<MoreHorizontalIcon />
+			<span className="sr-only">More</span>
+		</span>
+	);
+}
+
+export {
+	Breadcrumb,
+	BreadcrumbList,
+	BreadcrumbItem,
+	BreadcrumbLink,
+	BreadcrumbPage,
+	BreadcrumbSeparator,
+	BreadcrumbEllipsis,
+};