@api7/ui-components 0.6.0 → 0.8.0

package/README.md

@@ -16,14 +16,14 @@ yarn add @api7/ui-components tailwindcss react-day-picker lucide-react
 
 `tailwindcss` is already there if the application uses Tailwind. Install the integration of Tailwind for your build tool as well (`@tailwindcss/vite`, `@tailwindcss/postcss` or `@tailwindcss/cli`). The import of the theme works with the Vite plugin, the PostCSS plugin and the CLI, which are the ones tested. Other build tools, such as webpack, are not tested. The package expects these peer dependencies in the application:
 
-| Package                 | Version   | Needed for                                                                                                                                                    |
-| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `react`, `react-dom`    | `^19`     | Everything                                                                                                                                                    |
-| `tailwindcss`           | `^4.1.0`  | Compiles the classes of the components and registers the theme. See [Quick start](#quick-start)                                                               |
-| `lucide-react`          | `^1`      | Icons used inside components                                                                                                                                  |
-| `react-day-picker`      | `^10.0.1` | Required. `Calendar`, `DatePicker` and `DateRangePicker` import it, and the package declares it as a required peer, so install it even if you do not use them |
-| `@tanstack/react-form`  | `^1.33.0` | `@api7/ui-components/form` (optional)                                                                                                                         |
-| `@tanstack/react-table` | `^9.0.0`  | `@api7/ui-components/data-table` (optional)                                                                                                                   |
+| Package                 | Version   | Needed for                                                                                                                                                                               |
+| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react`, `react-dom`    | `^19`     | Everything                                                                                                                                                                               |
+| `tailwindcss`           | `^4.1.0`  | Compiles the classes of the components and registers the theme. See [Quick start](#quick-start)                                                                                          |
+| `lucide-react`          | `^1`      | Icons used inside components                                                                                                                                                             |
+| `react-day-picker`      | `^10.0.1` | Required. `Calendar`, `DatePicker`, `DateRangePicker` and `RelativeDateRangePicker` import it, and the package declares it as a required peer, so install it even if you do not use them |
+| `@tanstack/react-form`  | `^1.33.0` | `@api7/ui-components/form` (optional)                                                                                                                                                    |
+| `@tanstack/react-table` | `^9.0.0`  | `@api7/ui-components/data-table` (optional)                                                                                                                                              |
 
 Add the optional ones only if you import those entry points.
 
@@ -100,6 +100,10 @@ Add the optional ones only if you import those entry points.
 
 The package is ESM only. Component modules keep their `"use client"` directive, so the components work in a React Server Components setup such as the Next.js app router.
 
+## Code
+
+For inline code, highlighted code blocks, line numbers, wrapping and localized copy feedback, see [Code and CodeBlock](src/components/code/README.md). Both components and the reusable `useClipboard` hook are exported from the package root.
+
 ## Buttons
 
 `Button` takes a `variant`: `primary` (the default), `secondary`, `outline`, `ghost`, `destructive` or `link`. It takes a `size`: `sm`, `md` (the default), `lg` or `icon`. `loading` disables the button and shows a spinner, and `loadingLabel` sets the text that screen readers announce.
@@ -136,6 +140,45 @@ export function DocsLink() {
 }
 ```
 
+## Breadcrumbs
+
+Compose a `Breadcrumb` navigation region from `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage` and `BreadcrumbSeparator`. Links use muted text, the current page uses foreground text, and the list uses 14px text with 8px gaps.
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@api7/ui-components';
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/docs/components">Components</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>;
+```
+
+`BreadcrumbLink` renders an anchor. For a router link, pass `render={<Link to="/docs" />}` with your router's `Link`; it must forward props and its ref to an anchor. The render prop composes the link's handlers, styles and refs. `BreadcrumbPage` is noninteractive text with `aria-current="page"`. To keep the current page clickable, use `BreadcrumbLink` with `aria-current="page"` and `className="text-foreground"` instead.
+
+`BreadcrumbSeparator` defaults to a chevron and is hidden from assistive technology. Pass children to replace it, such as `<BreadcrumbSeparator>/</BreadcrumbSeparator>`, and place separators only between items. The navigation label comes from `ConfigProvider`'s `breadcrumb.label` message; override it with `aria-label` or `aria-labelledby` to distinguish multiple trails.
+
+Existing dictionaries typed as `Messages` can omit `breadcrumb`. `ConfigProvider` fills in the localized default, and `useMessages()` returns the complete messages.
+
+The list and long labels wrap within the available width. Each part accepts native props, a ref and `className`. Put icons, menus or loading placeholders inside an item as needed. Padding, background, sticky positioning and deciding when to show the trail belong to the application.
+
 ## Spinners
 
 `Spinner` is an SVG that spins, and it is a status, so a screen reader announces it. It takes a `size`: `xs`, `sm`, `md` (the default) or `lg`. Its colour is the text colour, so set it with a `text-*` class, and any other `className` is merged onto the SVG.
@@ -180,6 +223,76 @@ Things worth knowing before you build on it:
 - An indeterminate bar slides a segment along the track. When the user prefers reduced motion it shows the whole track at half opacity instead of a static segment, so it is not read as a partial value. The width of a determinate bar is animated too, and that stops as well.
 - The fill uses the text colour of each tone (`primary-text`, `success-foreground`, `warning-foreground` and `destructive-text`), because those stay 3:1 against the track in both themes, and the plain tone colours do not.
 
+## Combobox
+
+`Combobox` filters local options or accepts a `loadItems` callback for debounced remote search and paginated loading, including loading states and retry actions. Both modes use the same input, content, and selection parts. See the [Combobox guide](src/components/combobox/README.md) for the loader contract, selection, and changing data sources.
+
+## Cascader
+
+`Cascader` selects a hierarchical path in one popup, with optional intermediate selection, lazy children, loaded-path search, and keyboard navigation. See the [Cascader guide](src/components/cascader/README.md) for options, controlled values, loading, and form integration.
+
+## Collapsible
+
+`Collapsible` groups a disclosure trigger and its content. Use `defaultOpen` for local state, or `open` and `onOpenChange` to control it. The root also works without a trigger when another control owns its state.
+
+```tsx
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@api7/ui-components';
+
+<Collapsible defaultOpen>
+  <CollapsibleTrigger>Additional details</CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="pt-3">More information about this item.</div>
+  </CollapsibleContent>
+</Collapsible>;
+```
+
+`CollapsibleTrigger` renders a button with an automatically rotating chevron. It supports Enter and Space, exposes `aria-expanded` and `aria-controls`, and accepts `render={<Button variant="outline" />}` to compose with a button. `disabled` on the root or trigger prevents interaction. The root has no border or padding so it can fit within a navigation group, card or form.
+
+`CollapsibleContent` unmounts after closing by default. Set `keepMounted` on it to retain local state and uncontrolled form inputs while closed; hidden content is excluded from keyboard navigation. Put spacing on a child of the content, as in the example, so it collapses fully. The height and opacity transitions respect reduced motion. All parts accept native props, refs, `render` and a string `className`.
+
+For several sections, render one controlled `Collapsible` per item with a stable key. Store a single active ID to allow only one open section, or a list of IDs for independent expansion. The [Grouped Storybook example](../storybook/stories/components/collapsible/collapsible.stories.tsx) demonstrates independent panels, expand-all and collapse-all controls. When sections need headings, put each trigger inside a heading of the appropriate level and give its content `role="region"` and `aria-labelledby` pointing at the trigger's ID. Keep adjacent action buttons outside the heading and trigger.
+
+## Anchor navigation
+
+`Anchor` renders a table of contents as native links and follows the current section while scrolling. Each item has a unique same-document fragment `href`, a `title` (a React node) and optional nested `children`. Give the navigation an `aria-label` or `aria-labelledby`.
+
+The active link uses semibold primary text. The navigation has no vertical track, indicator bar or independent scrollbar; it stays alongside the scrolling page by default.
+
+```tsx
+import { Anchor } from '@api7/ui-components';
+
+const items = [
+  { href: '#overview', title: 'Overview' },
+  { href: '#settings', title: 'Settings', children: [{ href: '#notifications', title: 'Notifications' }] },
+];
+
+export function SettingsPage() {
+  return (
+    <div className="grid grid-cols-1 items-start gap-8 md:grid-cols-[200px_minmax(0,1fr)]">
+      <Anchor aria-label="On this page" className="static md:sticky" offsetTop={64} targetOffset={80} items={items} />
+      <main className="min-w-0 break-words">
+        <section id="overview">Overview content</section>
+        <section id="settings">Settings content</section>
+        <section id="notifications">Notification preferences</section>
+      </main>
+    </div>
+  );
+}
+```
+
+- Scrolling defaults to the window. For a scrollable element, pass `getContainer={() => scrollRef.current}`. Targets must be inside that container. Its border is excluded when calculating offsets.
+- Keep `items` and `getContainer` stable across unrelated renders, using a module-level array or `useMemo` for items and `useCallback` for the container getter. Changes to these props rebuild the scroll observers. `onActiveChange` can be an inline callback; its identity does not rebuild observers.
+- `sticky` defaults to `true`; `offsetTop` sets its CSS sticky offset in pixels, and `targetOffset` sets the scroll destination and active section threshold. `targetOffset` defaults to `offsetTop`, which defaults to zero. Sticky positioning is limited by the navigation's containing block, so keep it alongside the full content column, as above.
+- Clicks scroll smoothly without changing the URL or adding history entries. Set `scrollBehavior="instant"` for immediate scrolling or `updateHash` to add a fragment history entry on navigation. Reduced motion always uses instant scrolling. Modified clicks retain native browser behavior.
+- The clicked link stays active during smooth navigation. Scroll tracking resumes when the animation ends or the user interrupts it with a pointer, touch, wheel or scrolling key.
+- The first visible target is active before scrolling reaches it. The last target becomes active at the bottom, even if its section is short. Missing and hidden targets are skipped; changes to the items or document layout refresh the active section. `onActiveChange(href)` reports changes, including an empty string when no target remains.
+- Links remain keyboard accessible, use `aria-current="location"` for the active section, and move focus to the destination after navigation. `onNavigate(event, item)` can cancel a jump with `event.preventDefault()`.
+- The root accepts native `nav` props, including `ref`, `className` and `style`. Use the `anchor`, `anchor-list` and `anchor-link` data slots for more specific overrides. Width and surrounding layout belong to the application.
+
+## File selection and uploads
+
+`FileUpload` selects local files with type, size and custom validation, displays removable file rows, and shows loading or upload progress. It supports controlled and uncontrolled selections, multiple files, custom previews and a button-only layout. The application owns file reading and network requests. See the [FileUpload guide](src/components/file-upload/README.md) for the API and examples.
+
 ## Forms
 
 `@api7/ui-components/form` wraps TanStack Form. `useAppForm` returns a form whose `AppField` hands you ready made fields: `TextField`, `TextareaField`, `NumberField`, `SelectField`, `ComboboxField`, `DatePickerField`, `DateRangePickerField`, `CheckboxField`, `SwitchField` and `RadioGroupField`:
@@ -327,6 +440,52 @@ Things worth knowing before you build on it:
 - A value can hold any content. It grows with its content and long text wraps, so do not give a value a fixed height.
 - A tooltip in a label is a `Tooltip` you place there, and its trigger needs an accessible name, as it does anywhere else.
 
+## Steps
+
+`Steps` shows progress through an ordered sequence. It uses 24px indicators with dots for waiting and active steps, a check for completed steps and a cross for errors. Horizontal lists place labels below the indicators; `orientation="vertical"` places them beside the indicators.
+
+```tsx
+import { Button, Steps } from '@api7/ui-components';
+import { useState } from 'react';
+
+const items = [{ title: 'Details' }, { title: 'Review' }, { title: 'Publish' }];
+
+export function DocumentWizard() {
+  const [current, setCurrent] = useState(0);
+
+  return (
+    <div className="flex flex-col gap-6">
+      <Steps items={items} current={current} aria-label="Document publishing" />
+      <div hidden={current !== 0}>Document details</div>
+      <div hidden={current !== 1}>Review the document</div>
+      <div hidden={current !== 2}>Ready to publish</div>
+      <div className="flex justify-end gap-2">
+        <Button variant="outline" disabled={current === 0} onClick={() => setCurrent(current - 1)}>
+          Previous
+        </Button>
+        <Button disabled={current === items.length - 1} onClick={() => setCurrent(current + 1)}>
+          Next
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+| Prop              | Meaning                                                                                                                                                                                                                                                                                        |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`           | A readonly array of `StepsItem`: `title`, optional `description`, decorative `icon`, `status`, `disabled` and stable React `key`. Titles and descriptions accept non-interactive React content.                                                                                                |
+| `current`         | Zero-based active index, default 0. Earlier steps are complete and later steps are waiting. Set it to `items.length` after the operation succeeds to show completion without a current step. Finite indexes are rounded down and clamped to 0 through `items.length`; non-finite values use 0. |
+| `status`          | Status of the current step: `process` (default), `wait`, `finish` or `error`. An item's explicit status overrides the inferred status.                                                                                                                                                         |
+| `orientation`     | `horizontal` (default) or `vertical`. Choose vertical for long sequences in narrow containers.                                                                                                                                                                                                 |
+| `onStepChange`    | Optional `(index: number) => void`. Enables step buttons and requests a different index without changing `current` internally. The current step does not request a change.                                                                                                                     |
+| `disabled`        | Disables all step buttons. An individual item's `disabled` disables only that button. These props do not change progress status.                                                                                                                                                               |
+| Native list props | `className`, `style`, `ref`, `aria-label`, `aria-labelledby` and other ordered-list attributes are forwarded to the root.                                                                                                                                                                      |
+
+Without `onStepChange`, Steps is a read-only ordered list. With it, every step is a native button, reachable with Tab and activated with Enter or Space; disabled steps are skipped. The current step carries `aria-current="step"`. The list name and status descriptions come from `ConfigProvider` messages under `steps` (`label`, `wait`, `process`, `finish`, `error`), with English and Chinese defaults. Give each flow a meaningful `aria-label` or `aria-labelledby`.
+
+Steps does not own panels, validation or submission. Compose these with `Button`, using `disabled` and `loading` while validating or saving, and update `current` only when a transition succeeds. Keep panels mounted with `hidden` to retain form state, or store their values in the parent. To allow revisiting completed steps, supply `onStepChange` and disable steps that are not yet available. The Storybook `Wizard` example includes required input, backward navigation, retained values, loading and successful completion.
+
 ## Theming
 
 The library theme is the default theme of the application. The colors, the radii and the font are Tailwind theme variables, such as `--color-primary` and `--font-sans`, and the application overrides them in its own CSS after the import, as [Using it with your Tailwind CSS](#using-it-with-your-tailwind-css) explains. The light values are the values of the page, `[data-theme=light]` repeats them for a region, and `[data-theme=dark]` holds the dark values. The values themselves are in `src/tokens/semantic.ts`.
@@ -358,7 +517,7 @@ The components are ordinary Tailwind utilities, so there is one stylesheet and o
 What the theme changes in the application:
 
 - It adds the semantic colors to the Tailwind theme: `background`, `foreground`, `card`, `popover`, `primary`, `primary-text`, `muted`, `accent`, `destructive`, `success`, `warning`, `info`, `border`, `input`, `ring` and the others listed in `src/tokens/semantic.ts`. The names are common, so an application that already defines `--color-primary` or `--color-muted` gets the value of whichever declaration comes last.
-- It sets `rounded-sm` to 2px and `rounded-md` to 4px, for the application's own markup as well. Other radii and the whole color palette stay as Tailwind defines them.
+- It sets `rounded-sm` to 2px, `rounded-md` to 4px and `rounded-lg` to 8px, for the application's own markup as well. The 8px size is for outer containers, while the existing control sizes stay unchanged. Other radii and the whole color palette stay as Tailwind defines them.
 - It sets `--font-sans`. Tailwind's theme points `--default-font-family` at it, so Inter becomes the default font of the whole application, not only of the `font-sans` utility.
 - It defines the `dark` variant, as described in [Dark mode](#dark-mode).
 
@@ -395,3 +554,5 @@ import { Popover, PopoverArrow, PopoverContent, PopoverTrigger } from '@api7/ui-
   </PopoverContent>
 </Popover>;
 ```
+
+See the [DataTable guide](src/components/data-table/README.md) for column sizing, pinned columns, successive table groups, custom column filters, and expanded detail rows.

package/dist/components/anchor/anchor.d.ts

@@ -0,0 +1,28 @@
+import { ComponentProps, MouseEvent, ReactNode } from "react";
+export interface AnchorItem {
+  /** A unique fragment link to an element in the same document. */
+  href: string;
+  title: ReactNode;
+  children?: readonly AnchorItem[];
+}
+export type AnchorProps = Omit<ComponentProps<'nav'>, 'children'> & {
+  /** Keep the array identity stable when the items have not changed. */
+  items: readonly AnchorItem[];
+  /** The scrolling element. Defaults to the window. Memoize the callback to avoid rebuilding observers. */
+  getContainer?: () => HTMLElement | Window | null;
+  /** Keeps the navigation sticky within its containing block. Defaults to true. */
+  sticky?: boolean;
+  /** Sticky navigation offset in pixels. Defaults to 0. */
+  offsetTop?: number;
+  /** Scroll destination and active section offset in pixels. Defaults to offsetTop. */
+  targetOffset?: number;
+  /** Defaults to smooth. Reduced motion always uses instant scrolling. */
+  scrollBehavior?: ScrollBehavior;
+  /** Adds a history entry on navigation. Defaults to false. */
+  updateHash?: boolean;
+  onActiveChange?: (href: string) => void;
+  /** Prevent the default event to cancel navigation. */
+  onNavigate?: (event: MouseEvent<HTMLAnchorElement>, item: AnchorItem) => void;
+};
+declare function Anchor({ items, getContainer, sticky, offsetTop, targetOffset, scrollBehavior, updateHash, onActiveChange, onNavigate, className, style, ...props }: AnchorProps): import("react").JSX.Element;
+export { Anchor };

package/dist/components/anchor/anchor.js

@@ -0,0 +1,249 @@
+"use client";
+import { cn } from "../../lib/cn.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/components/anchor/anchor.tsx
+function flattenItems(items) {
+	return items.flatMap((item) => [item, ...flattenItems(item.children ?? [])]);
+}
+function getTarget(href, container) {
+	if (!href.startsWith("#") || href.length === 1) return null;
+	let id = href.slice(1);
+	try {
+		id = decodeURIComponent(id);
+	} catch {}
+	const target = document.getElementById(id);
+	if (!target || container instanceof HTMLElement && !container.contains(target)) return null;
+	if (!target.getClientRects().length || getComputedStyle(target).visibility === "hidden") return null;
+	return target;
+}
+function getScrollPosition(container) {
+	if (container instanceof HTMLElement) return {
+		top: container.getBoundingClientRect().top + container.clientTop,
+		scrollTop: container.scrollTop,
+		height: container.clientHeight,
+		scrollHeight: container.scrollHeight
+	};
+	return {
+		top: 0,
+		scrollTop: window.scrollY,
+		height: window.innerHeight,
+		scrollHeight: document.documentElement.scrollHeight
+	};
+}
+function trackScroll(container, onFinish) {
+	let timeout;
+	const scrollEndTarget = container instanceof HTMLElement ? container : document;
+	const cleanup = () => {
+		clearTimeout(timeout);
+		container.removeEventListener("scroll", onScroll);
+		scrollEndTarget.removeEventListener("scrollend", finish);
+		for (const type of [
+			"wheel",
+			"touchstart",
+			"pointerdown",
+			"keydown"
+		]) container.removeEventListener(type, interrupt);
+	};
+	const finish = (event) => {
+		if (event && event.target !== scrollEndTarget) return;
+		cleanup();
+		onFinish();
+	};
+	const onScroll = () => {
+		clearTimeout(timeout);
+		timeout = setTimeout(finish, 200);
+	};
+	const interrupt = (event) => {
+		if (event instanceof KeyboardEvent && ![
+			"ArrowUp",
+			"ArrowDown",
+			"PageUp",
+			"PageDown",
+			"Home",
+			"End",
+			" "
+		].includes(event.key)) return;
+		container.scrollTo({
+			top: getScrollPosition(container).scrollTop,
+			behavior: "instant"
+		});
+		finish();
+	};
+	container.addEventListener("scroll", onScroll, { passive: true });
+	scrollEndTarget.addEventListener("scrollend", finish);
+	for (const type of [
+		"wheel",
+		"touchstart",
+		"pointerdown",
+		"keydown"
+	]) container.addEventListener(type, interrupt, { passive: true });
+	onScroll();
+	return cleanup;
+}
+function Anchor({ items, getContainer, sticky = true, offsetTop = 0, targetOffset = offsetTop, scrollBehavior = "smooth", updateHash = false, onActiveChange, onNavigate, className, style, ...props }) {
+	const links = useMemo(() => flattenItems(items), [items]);
+	const [activeHref, setActiveHref] = useState("");
+	const activeRef = useRef("");
+	const onActiveChangeRef = useRef(onActiveChange);
+	useEffect(() => {
+		onActiveChangeRef.current = onActiveChange;
+	}, [onActiveChange]);
+	const scheduleUpdateRef = useRef(void 0);
+	const scrollingToRef = useRef(null);
+	const clearScrollTracking = useCallback(() => {
+		scrollingToRef.current?.cleanup();
+		scrollingToRef.current = null;
+	}, []);
+	const restoreFocusTarget = useRef(void 0);
+	useEffect(() => () => {
+		restoreFocusTarget.current?.();
+		clearScrollTracking();
+	}, [clearScrollTracking]);
+	const changeActive = useCallback((href) => {
+		if (href === activeRef.current) return;
+		activeRef.current = href;
+		setActiveHref(href);
+		onActiveChangeRef.current?.(href);
+	}, []);
+	useEffect(() => {
+		const container = getContainer ? getContainer() : window;
+		if (!container) return;
+		let frame = 0;
+		const update = () => {
+			frame = 0;
+			const scrollingTo = scrollingToRef.current;
+			if (scrollingTo) {
+				if (scrollingTo.container === container && links.some((item) => item.href === scrollingTo.href) && getTarget(scrollingTo.href, container)) return;
+				clearScrollTracking();
+			}
+			const position = getScrollPosition(container);
+			const targets = links.flatMap((item) => {
+				const target = getTarget(item.href, container);
+				return target ? [{
+					href: item.href,
+					top: target.getBoundingClientRect().top
+				}] : [];
+			});
+			targets.sort((a, b) => a.top - b.top);
+			let current = targets[0]?.href ?? "";
+			for (const target of targets) if (target.top <= position.top + targetOffset + 1) current = target.href;
+			if (position.scrollTop > 0 && position.scrollTop + position.height >= position.scrollHeight - 1) current = targets.at(-1)?.href ?? "";
+			changeActive(current);
+		};
+		const scheduleUpdate = () => {
+			if (!frame) frame = requestAnimationFrame(update);
+		};
+		scheduleUpdateRef.current = scheduleUpdate;
+		const root = container instanceof HTMLElement ? container : document.body;
+		const resizeObserver = new ResizeObserver(scheduleUpdate);
+		const observeTargets = () => {
+			resizeObserver.disconnect();
+			resizeObserver.observe(root);
+			for (const item of links) {
+				const target = getTarget(item.href, container);
+				if (target) resizeObserver.observe(target);
+			}
+		};
+		const mutationObserver = new MutationObserver(() => {
+			observeTargets();
+			scheduleUpdate();
+		});
+		observeTargets();
+		mutationObserver.observe(root, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [
+				"id",
+				"hidden",
+				"class",
+				"style"
+			]
+		});
+		container.addEventListener("scroll", scheduleUpdate, { passive: true });
+		window.addEventListener("resize", scheduleUpdate);
+		scheduleUpdate();
+		return () => {
+			scheduleUpdateRef.current = void 0;
+			cancelAnimationFrame(frame);
+			resizeObserver.disconnect();
+			mutationObserver.disconnect();
+			container.removeEventListener("scroll", scheduleUpdate);
+			window.removeEventListener("resize", scheduleUpdate);
+		};
+	}, [
+		links,
+		getContainer,
+		targetOffset,
+		changeActive,
+		clearScrollTracking
+	]);
+	const navigate = (event, item) => {
+		onNavigate?.(event, item);
+		if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		if (!item.href.startsWith("#")) return;
+		event.preventDefault();
+		const container = getContainer ? getContainer() : window;
+		if (!container) return;
+		const target = getTarget(item.href, container);
+		if (!target) return;
+		const position = getScrollPosition(container);
+		const top = target.getBoundingClientRect().top - position.top + position.scrollTop - targetOffset;
+		const behavior = window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "instant" : scrollBehavior;
+		clearScrollTracking();
+		const destination = Math.max(0, Math.min(top, position.scrollHeight - position.height));
+		if (behavior !== "instant" && Math.abs(destination - position.scrollTop) > 1) scrollingToRef.current = {
+			container,
+			href: item.href,
+			cleanup: trackScroll(container, () => {
+				scrollingToRef.current = null;
+				scheduleUpdateRef.current?.();
+			})
+		};
+		restoreFocusTarget.current?.();
+		if (!target.hasAttribute("tabindex")) {
+			target.setAttribute("tabindex", "-1");
+			const restore = () => {
+				if (target.getAttribute("tabindex") === "-1") target.removeAttribute("tabindex");
+				target.removeEventListener("blur", restore);
+				restoreFocusTarget.current = void 0;
+			};
+			restoreFocusTarget.current = restore;
+			target.addEventListener("blur", restore, { once: true });
+		}
+		target.focus({ preventScroll: true });
+		container.scrollTo({
+			top,
+			behavior
+		});
+		changeActive(item.href);
+		scheduleUpdateRef.current?.();
+		if (updateHash && window.location.hash !== item.href) window.history.pushState(window.history.state, "", item.href);
+	};
+	const renderItems = (entries, depth = 0) => /* @__PURE__ */ jsx("ul", {
+		className: "m-0 list-none p-0",
+		"data-slot": "anchor-list",
+		children: entries.map((item) => /* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("a", {
+			href: item.href,
+			"aria-current": activeHref === item.href ? "location" : void 0,
+			"data-active": activeHref === item.href ? "" : void 0,
+			"data-slot": "anchor-link",
+			className: cn("block rounded-sm pr-3 text-sm leading-[1.8] break-words text-muted-foreground no-underline outline-none hover:text-primary-text focus-visible:ring-2 focus-visible:ring-ring/40 data-active:font-semibold data-active:text-primary-text", depth === 0 ? "py-1" : "py-0.5"),
+			style: { paddingLeft: 16 + depth * 16 },
+			onClick: (event) => navigate(event, item),
+			children: item.title
+		}), item.children?.length ? renderItems(item.children, depth + 1) : null] }, item.href))
+	});
+	return /* @__PURE__ */ jsx("nav", {
+		className: cn("relative min-w-0", sticky && "sticky self-start", className),
+		style: {
+			...sticky ? { top: offsetTop } : {},
+			...style
+		},
+		...props,
+		"data-slot": "anchor",
+		children: renderItems(items)
+	});
+}
+export { Anchor };

package/dist/components/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,15 @@
+import { ComponentProps } from "react";
+import { useRender } from "@base-ui/react/use-render";
+export type BreadcrumbProps = ComponentProps<'nav'>;
+declare function Breadcrumb({ className, ...props }: BreadcrumbProps): import("react").JSX.Element;
+export type BreadcrumbListProps = ComponentProps<'ol'>;
+declare function BreadcrumbList({ className, ...props }: BreadcrumbListProps): import("react").JSX.Element;
+export type BreadcrumbItemProps = ComponentProps<'li'>;
+declare function BreadcrumbItem({ className, ...props }: BreadcrumbItemProps): import("react").JSX.Element;
+export type BreadcrumbLinkProps = useRender.ComponentProps<'a'>;
+declare function BreadcrumbLink({ render, className, ...props }: BreadcrumbLinkProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type BreadcrumbPageProps = ComponentProps<'span'>;
+declare function BreadcrumbPage({ className, ...props }: BreadcrumbPageProps): import("react").JSX.Element;
+export type BreadcrumbSeparatorProps = ComponentProps<'li'>;
+declare function BreadcrumbSeparator({ className, children, ...props }: BreadcrumbSeparatorProps): import("react").JSX.Element;
+export { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator };

package/dist/components/breadcrumb/breadcrumb.js

@@ -0,0 +1,60 @@
+"use client";
+import { useMessages } from "../../config/config-provider.js";
+import { cn } from "../../lib/cn.js";
+import { jsx } from "react/jsx-runtime";
+import { ChevronRight } from "lucide-react";
+import { useRender } from "@base-ui/react/use-render";
+// src/components/breadcrumb/breadcrumb.tsx
+function Breadcrumb({ className, ...props }) {
+	const messages = useMessages();
+	return /* @__PURE__ */ jsx("nav", {
+		"aria-label": messages.breadcrumb.label,
+		className: cn("text-sm", className),
+		...props,
+		"data-slot": "breadcrumb"
+	});
+}
+function BreadcrumbList({ className, ...props }) {
+	return /* @__PURE__ */ jsx("ol", {
+		className: cn("flex flex-wrap items-center gap-2 text-muted-foreground", className),
+		...props,
+		"data-slot": "breadcrumb-list"
+	});
+}
+function BreadcrumbItem({ className, ...props }) {
+	return /* @__PURE__ */ jsx("li", {
+		className: cn("inline-flex min-w-0 max-w-full items-center gap-2", className),
+		...props,
+		"data-slot": "breadcrumb-item"
+	});
+}
+function BreadcrumbLink({ render, className, ...props }) {
+	return useRender({
+		defaultTagName: "a",
+		render,
+		props: {
+			...props,
+			className: cn("min-w-0 rounded-sm wrap-anywhere outline-none hover:text-foreground hover:underline focus-visible:ring-2 focus-visible:ring-ring/40", className),
+			"data-slot": "breadcrumb-link"
+		}
+	});
+}
+function BreadcrumbPage({ className, ...props }) {
+	return /* @__PURE__ */ jsx("span", {
+		"aria-current": "page",
+		className: cn("min-w-0 text-foreground wrap-anywhere", className),
+		...props,
+		"data-slot": "breadcrumb-page"
+	});
+}
+function BreadcrumbSeparator({ className, children, ...props }) {
+	return /* @__PURE__ */ jsx("li", {
+		className: cn("inline-flex shrink-0 items-center [&>svg]:size-4", className),
+		...props,
+		role: "presentation",
+		"aria-hidden": "true",
+		"data-slot": "breadcrumb-separator",
+		children: children ?? /* @__PURE__ */ jsx(ChevronRight, {})
+	});
+}
+export { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator };

package/dist/components/button/button.d.ts

@@ -1,5 +1,5 @@
-import { VariantProps } from "class-variance-authority";
 import { Button } from "@base-ui/react/button";
+import { VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
   variant?: "primary" | "secondary" | "destructive" | "link" | "outline" | "ghost" | null | undefined;
   size?: "sm" | "md" | "lg" | "icon" | null | undefined;

package/dist/components/button/button.js

@@ -2,9 +2,9 @@
 import { useMessages } from "../../config/config-provider.js";
 import { cn } from "../../lib/cn.js";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Button } from "@base-ui/react/button";
 import { cva } from "class-variance-authority";
 import { LoaderCircle } from "lucide-react";
-import { Button } from "@base-ui/react/button";
 // src/components/button/button.tsx
 const buttonVariants = cva("inline-flex shrink-0 items-center justify-center gap-2 rounded-md border border-transparent text-sm font-medium whitespace-nowrap transition-colors outline-none select-none focus-visible:ring-2 focus-visible:ring-ring/40 disabled:pointer-events-none disabled:opacity-50 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5", {
 	variants: {