diff --git a/packages/origin/src/components/Field/Field.test-stories.tsx b/packages/origin/src/components/Field/Field.test-stories.tsx
index 8d31dd036..ef2a7a378 100644
--- a/packages/origin/src/components/Field/Field.test-stories.tsx
+++ b/packages/origin/src/components/Field/Field.test-stories.tsx
@@ -4,6 +4,13 @@ import * as React from "react";
import { Field } from "./";
import { Input } from "@/components/Input";
+const RenderedRoot = React.forwardRef<
+ HTMLElement,
+ React.ComponentPropsWithoutRef<"section">
+>(function RenderedRoot(props, ref) {
+ return
;
+});
+
export function DefaultField() {
return (
@@ -14,6 +21,18 @@ export function DefaultField() {
);
}
+export function FieldWithLabelSuffix() {
+ return (
+
+
+ Display name
+ (optional)
+
+
+ );
+}
+
export function FieldWithError() {
return (
@@ -104,3 +123,45 @@ export function FieldWithName() {
);
}
+
+export function FieldWithRenderedRoot() {
+ return (
+ Email
+ Enter a valid email address.
+
+ );
+}
+
+export function FieldWithStatefulRootClassName() {
+ return (
+
+ state.valid === false
+ ? "consumer-field-root-invalid"
+ : "consumer-field-root-valid"
+ }
+ render={
+ Email
+ Enter a valid email address.
+
+ );
+}
diff --git a/packages/origin/src/components/Field/Field.test.tsx b/packages/origin/src/components/Field/Field.test.tsx
index 0e70c9d91..29af9ee59 100644
--- a/packages/origin/src/components/Field/Field.test.tsx
+++ b/packages/origin/src/components/Field/Field.test.tsx
@@ -1,6 +1,7 @@
import { test, expect } from "@playwright/experimental-ct-react";
import {
DefaultField,
+ FieldWithLabelSuffix,
FieldWithError,
DisabledField,
FieldWithoutLabel,
@@ -8,6 +9,8 @@ import {
ControlledField,
FieldWithValidation,
FieldWithName,
+ FieldWithRenderedRoot,
+ FieldWithStatefulRootClassName,
} from "./Field.test-stories";
test.describe("Field", () => {
@@ -24,6 +27,22 @@ test.describe("Field", () => {
await expect(description).toBeVisible();
});
+ test("spaces label suffix children with the spacing token", async ({
+ mount,
+ page,
+ }) => {
+ await mount(
);
+
+ const label = page.getByTestId("field-label-with-suffix");
+ const suffix = page.getByTestId("field-label-suffix");
+
+ await expect(label).toBeVisible();
+ await expect(label).toHaveCSS("display", "flex");
+ await expect(label).toHaveCSS("gap", "4px");
+ await expect(label).toContainText("Display name");
+ await expect(suffix).toHaveText("(optional)");
+ });
+
test("label is associated with input via aria", async ({ mount, page }) => {
await mount(
);
@@ -195,4 +214,41 @@ test.describe("Field", () => {
await expect(input).toBeVisible();
});
});
+
+ test.describe("render prop", () => {
+ test("renders a custom root while preserving Origin and consumer classes", async ({
+ mount,
+ page,
+ }) => {
+ await mount(
);
+
+ const root = page.getByTestId("rendered-field-root");
+ await expect(root).toBeVisible();
+ await expect(root).toHaveJSProperty("tagName", "SECTION");
+ await expect(root).toHaveAttribute("data-custom-root", "");
+ await expect(root).toHaveAttribute("data-invalid", "");
+ await expect(root).toHaveCSS("display", "flex");
+ await expect(root).toHaveCSS("flex-direction", "column");
+ await expect(root).toHaveClass(/consumer-field-root/);
+ await expect(root).toHaveClass(/rendered-field-root/);
+ });
+
+ test("supports stateful root class names with a rendered root class", async ({
+ mount,
+ page,
+ }) => {
+ await mount(
);
+
+ const root = page.getByTestId("stateful-class-field-root");
+ await expect(root).toBeVisible();
+ await expect(root).toHaveJSProperty("tagName", "SECTION");
+ await expect(root).toHaveAttribute("data-custom-root", "");
+ await expect(root).toHaveAttribute("data-invalid", "");
+ await expect(root).toHaveCSS("display", "flex");
+ await expect(root).toHaveCSS("flex-direction", "column");
+ await expect(root).toHaveClass(/consumer-field-root-invalid/);
+ await expect(root).toHaveClass(/rendered-stateful-field-root/);
+ await expect(root).not.toHaveClass(/consumer-field-root-valid/);
+ });
+ });
});
diff --git a/packages/origin/src/components/Field/parts.tsx b/packages/origin/src/components/Field/parts.tsx
index 3c3092670..e7f600065 100644
--- a/packages/origin/src/components/Field/parts.tsx
+++ b/packages/origin/src/components/Field/parts.tsx
@@ -6,19 +6,20 @@ import clsx from "clsx";
import styles from "./Field.module.scss";
export interface FieldRootProps
- extends Omit<
- React.ComponentPropsWithoutRef
,
- "render"
- > {}
+ extends React.ComponentPropsWithoutRef {}
-export const FieldRoot = React.forwardRef(
+export const FieldRoot = React.forwardRef(
function FieldRoot(props, ref) {
const { className, children, ...other } = props;
+ const rootClassName: FieldRootProps["className"] =
+ typeof className === "function"
+ ? (state) => clsx(styles.root, className(state))
+ : clsx(styles.root, className);
return (
}
+ className={rootClassName}
{...other}
>
{children}
diff --git a/packages/origin/src/components/Form/FormCompositionBoundary.test-stories.tsx b/packages/origin/src/components/Form/FormCompositionBoundary.test-stories.tsx
new file mode 100644
index 000000000..d104635b0
--- /dev/null
+++ b/packages/origin/src/components/Form/FormCompositionBoundary.test-stories.tsx
@@ -0,0 +1,421 @@
+"use client";
+
+import * as React from "react";
+import { Button } from "@/components/Button";
+import { Checkbox } from "@/components/Checkbox";
+import { Combobox } from "@/components/Combobox";
+import { Field } from "@/components/Field";
+import { Input } from "@/components/Input";
+import { Select } from "@/components/Select";
+import { Form } from "./Form";
+
+type ProductOption = {
+ value: string;
+ label: string;
+};
+
+const entityTypeOptions: ProductOption[] = [
+ { value: "corporation", label: "Corporation" },
+ { value: "llc", label: "Limited liability company" },
+ { value: "partnership", label: "Partnership" },
+];
+
+const countryOptions: ProductOption[] = [
+ { value: "US", label: "United States" },
+ { value: "CA", label: "Canada" },
+ { value: "GB", label: "United Kingdom" },
+];
+
+const businessTypeOptions: ProductOption[] = [
+ { value: "marketplace", label: "Marketplace" },
+ { value: "financial-services", label: "Financial services" },
+ { value: "software", label: "Software" },
+];
+
+const ownerRoleOptions: ProductOption[] = [
+ { value: "control-person", label: "Control person" },
+ { value: "beneficial-owner", label: "Beneficial owner" },
+ { value: "signer", label: "Signer" },
+];
+
+const ownerRoleValues = ownerRoleOptions.map((option) => option.value);
+
+const RenderedFormFieldRoot = React.forwardRef<
+ HTMLElement,
+ React.ComponentPropsWithoutRef<"section">
+>(function RenderedFormFieldRoot(props, ref) {
+ return ;
+});
+
+function getLabel(options: ProductOption[], value: string | null) {
+ return options.find((option) => option.value === value)?.label ?? value;
+}
+
+function removeError(errors: Record, name: string) {
+ const { [name]: _removed, ...remaining } = errors;
+ return remaining;
+}
+
+/**
+ * Form composition boundary coverage for KYB-shaped product forms.
+ *
+ * This is intentionally not a product migration or a product adapter. It keeps
+ * product state as strings, maps `{ value, label }` options at the call site,
+ * and uses Origin primitives directly.
+ *
+ * Current composition boundaries to keep visible:
+ * - `Field.Root render` is part of the supported contract: root slot
+ * replacement keeps Origin styling, merged classes, and Form invalid state.
+ * - Composite fields receive invalid state from `Form errors` when the
+ * `Field.Root name` matches the errors key. Product-owned errors outside
+ * `Form errors` still need explicit `invalid` wiring.
+ */
+export function KybOriginFormCompositionBoundary() {
+ const [legalName, setLegalName] = React.useState("");
+ const [entityType, setEntityType] = React.useState(null);
+ const [registrationCountry, setRegistrationCountry] = React.useState<
+ string | null
+ >(null);
+ const [countrySearch, setCountrySearch] = React.useState("");
+ const [countryOpen, setCountryOpen] = React.useState(false);
+ const [serverErrors, setServerErrors] = React.useState<
+ Record
+ >({});
+ const [businessPurpose, setBusinessPurpose] = React.useState("");
+ const [businessPurposeError, setBusinessPurposeError] = React.useState("");
+ const [comboboxRoles, setComboboxRoles] = React.useState([]);
+ const [checkboxRoles, setCheckboxRoles] = React.useState([
+ "control-person",
+ ]);
+ const [countryPortal, setCountryPortal] =
+ React.useState(null);
+ const legalNameInputRef = React.useRef(null);
+ const registrationCountryInputRef = React.useRef(null);
+
+ const selectedCountry =
+ countryOptions.find((option) => option.value === registrationCountry) ??
+ null;
+
+ const handleLegalNameChange = (value: string) => {
+ setLegalName(value);
+ setServerErrors((current) => removeError(current, "legalName"));
+ };
+
+ const handleCountryChange = (option: ProductOption | null) => {
+ setRegistrationCountry(option?.value ?? null);
+ setServerErrors((current) => removeError(current, "registrationCountry"));
+ };
+
+ const handleBusinessPurposeChange = (value: string) => {
+ setBusinessPurpose(value);
+ if (businessPurposeError && value.trim()) {
+ setBusinessPurposeError("");
+ }
+ };
+
+ const handleSubmit = (event: React.FormEvent) => {
+ event.preventDefault();
+
+ const nextErrors: Record = {};
+ if (!legalName.trim()) {
+ nextErrors.legalName = "Enter a legal business name";
+ }
+ if (!registrationCountry) {
+ nextErrors.registrationCountry = "Select a registration country";
+ }
+
+ setServerErrors(nextErrors);
+ setBusinessPurposeError(
+ businessPurpose.trim() ? "" : "Enter a business purpose",
+ );
+
+ const firstInvalidInput = nextErrors.legalName
+ ? legalNameInputRef.current
+ : nextErrors.registrationCountry
+ ? registrationCountryInputRef.current
+ : null;
+ firstInvalidInput?.focus();
+ };
+
+ return (
+
+
+
+
+ {legalName || "no legal name"}
+
+
{entityType ?? "none"}
+
+ {registrationCountry ?? "none"}
+
+
+ {countrySearch || "empty"}
+
+
+ {countryOpen ? "open" : "closed"}
+
+
+ {comboboxRoles.join(",") || "none"}
+
+
+ {checkboxRoles.join(",") || "none"}
+
+
+ {items.map((item) => (
+
+ {item.label}
+
+ ))}
+
+ );
+}
+
+const meta: Meta = {
+ title: "Components/LoadMore",
+ component: LoadMore.Root,
+ parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const ManualTrigger: Story = {
+ render: () => {
+ const [items, setItems] = React.useState(() => generatePage(0, 10));
+ const [loading, setLoading] = React.useState(false);
+ const [hasMore, setHasMore] = React.useState(true);
+
+ const onLoadMore = () => {
+ setLoading(true);
+ setTimeout(() => {
+ setItems((prev) => {
+ const next = [...prev, ...generatePage(prev.length, 10)];
+ if (next.length >= 30) setHasMore(false);
+ return next;
+ });
+ setLoading(false);
+ }, 600);
+ };
+
+ return (
+
+
+
+
+ );
+ },
+};
+
+export const AutoSentinel: Story = {
+ render: () => {
+ const { items, hasMore, loading, loadingMore, loadMore } =
+ useLoadMore- ({
+ fetchPage: async (cursor) => {
+ const offset = cursor ? Number(cursor) : 0;
+ await new Promise((r) => setTimeout(r, 500));
+ const data = generatePage(offset, 10);
+ const next = offset + 10;
+ return {
+ data,
+ nextCursor: next < 50 ? String(next) : undefined,
+ hasMore: next < 50,
+ };
+ },
+ });
+
+ return (
+
+
+
+ {({ loading, hasMore }) =>
+ loading
+ ? "Loading more results"
+ : !hasMore
+ ? "End of results"
+ : ""
+ }
+
+
+
+ );
+ },
+};
+
+export const SentinelWithFallbackTrigger: Story = {
+ render: () => {
+ const { items, hasMore, loading, loadingMore, loadMore } =
+ useLoadMore- ({
+ fetchPage: async (cursor) => {
+ const offset = cursor ? Number(cursor) : 0;
+ await new Promise((r) => setTimeout(r, 400));
+ const data = generatePage(offset, 5);
+ const next = offset + 5;
+ return {
+ data,
+ nextCursor: next < 25 ? String(next) : undefined,
+ hasMore: next < 25,
+ };
+ },
+ });
+
+ return (
+
+
+
+
+
+
+ {({ loading, hasMore }) =>
+ loading
+ ? "Loading more results"
+ : !hasMore
+ ? "End of results"
+ : ""
+ }
+
+
+
+ undefined}
+ >
+
+ {({ hasMore }) => (!hasMore ? "End of results" : "")}
+
+
+
+ ),
+};
+
+export const LoadingState: Story = {
+ render: () => (
+
+ undefined}>
+
+
+ ),
+};
+
+export const CustomTriggerRender: Story = {
+ render: () => (
+ undefined}>
+ Show more} />
+
+ ),
+};
+
+export const WithFilterReset: Story = {
+ render: () => {
+ const [filter, setFilter] = React.useState("all");
+ const { items, hasMore, loading, loadingMore, loadMore } =
+ useLoadMore- ({
+ fetchPage: async (cursor) => {
+ const offset = cursor ? Number(cursor) : 0;
+ await new Promise((r) => setTimeout(r, 300));
+ const data = generatePage(offset, 5).map((item) => ({
+ ...item,
+ label: `${filter}: ${item.label}`,
+ }));
+ const next = offset + 5;
+ return {
+ data,
+ nextCursor: next < 20 ? String(next) : undefined,
+ hasMore: next < 20,
+ };
+ },
+ resetOn: [filter],
+ });
+
+ return (
+
+
+ {["all", "starred", "archived"].map((value) => (
+ setFilter(value)}
+ style={{ fontWeight: filter === value ? 700 : 400 }}
+ >
+ {value}
+
+ ))}
+
+
+
+
+
setCount((c) => c + 1)}
+ >
+ Loads: {count}
+
+ );
+}
+
+export function TriggerEnabled() {
+ return setCount((c) => c + 1)}
+ >
+ Show more} />
+ Loads: {count}
+
+ );
+}
+
+function SentinelHarness({
+ initialHasMore = true,
+ hold = false,
+}: {
+ initialHasMore?: boolean;
+ hold?: boolean;
+}) {
+ const [count, setCount] = React.useState(0);
+ const [hasMore, setHasMore] = React.useState(initialHasMore);
+ const [loading, setLoading] = React.useState(false);
+
+ const onLoadMore = React.useCallback(() => {
+ setCount((c) => c + 1);
+ if (hold) {
+ setLoading(true);
+ return;
+ }
+ setLoading(true);
+ setTimeout(() => {
+ setLoading(false);
+ setHasMore(false);
+ }, 50);
+ }, [hold]);
+
+ return (
+
+
+
+ Loads: {count}
+
+
undefined}>
+
+ );
+}
+
+export function StatusAnnouncements({
+ hasMore = true,
+ loading = false,
+}: {
+ hasMore?: boolean;
+ loading?: boolean;
+}) {
+ return (
+ undefined}
+ >
+
+ {({ loading, hasMore }) =>
+ loading
+ ? "Loading more results"
+ : !hasMore
+ ? "End of results"
+ : "More available"
+ }
+
+
+ );
+}
+
+export function StatusLoading() {
+ return
+
+ );
+}
+
+class ErrorBoundary extends React.Component<
+ { children: React.ReactNode },
+ { error: Error | null }
+> {
+ state = { error: null as Error | null };
+ static getDerivedStateFromError(error: Error) {
+ return { error };
+ }
+ render() {
+ if (this.state.error) {
+ return {this.state.error.message}
;
+ }
+ return this.props.children;
+ }
+}
+
+export function AnalyticsTrigger() {
+ const [events, setEvents] = React.useState([]);
+ const handler = React.useMemo(
+ () => ({
+ onInteraction: (info) => setEvents((prev) => [...prev, info]),
+ }),
+ [],
+ );
+
+ return (
+
+ undefined}
+ analyticsName="results"
+ >
+
+ {JSON.stringify(events)}
+
+ );
+}
+
+export function HookIntegration() {
+ const fetchPage = React.useCallback(async (cursor: string | undefined) => {
+ const offset = cursor ? Number(cursor) : 0;
+ const data = Array.from({ length: 5 }, (_, i) => ({
+ id: `${offset + i}`,
+ }));
+ const next = offset + 5;
+ return {
+ data,
+ nextCursor: next < 15 ? String(next) : undefined,
+ hasMore: next < 15,
+ };
+ }, []);
+
+ const { items, hasMore, loading, loadingMore, loadMore } = useLoadMore<{
+ id: string;
+ }>({
+ fetchPage,
+ });
+
+ return (
+
+
+ {items.map((item) => (
+ {item.id}
+ ))}
+
+
+
+
/,
+ );
+ });
+});
+
+test.describe("Analytics", () => {
+ test("emits LoadMore.click with part metadata when analyticsName is set", async ({
+ mount,
+ page,
+ }) => {
+ await mount((null);
+
+/** Access the surrounding `LoadMore.Root` state. Throws if used outside one. */
+export function useLoadMoreContext(): LoadMoreContextValue {
+ const context = React.useContext(LoadMoreContext);
+ if (context === null) {
+ throw new Error("LoadMore parts must be placed within .");
+ }
+ return context;
+}
+
+export interface LoadMoreRootProps {
+ /** Whether more items are available. */
+ hasMore: boolean;
+ /**
+ * Whether a load is currently in flight. Trigger and Sentinel use this to
+ * disable themselves and prevent re-firing.
+ */
+ loading: boolean;
+ /** Called when the user (or sentinel intersection) requests another page. */
+ onLoadMore: () => void;
+ /**
+ * Optional analytics identifier. Trigger emits `${name}.click` (interaction
+ * `click`) and Sentinel emits `${name}.intersect` (interaction `intersect`)
+ * with metadata `{ part: "trigger" | "sentinel" }`.
+ */
+ analyticsName?: string;
+ children?: React.ReactNode;
+}
+
+/** Headless context provider — renders only its children. */
+export function LoadMoreRoot(props: LoadMoreRootProps) {
+ const { hasMore, loading, onLoadMore, analyticsName, children } = props;
+
+ const value = React.useMemo(
+ () => ({ hasMore, loading, onLoadMore, analyticsName }),
+ [hasMore, loading, onLoadMore, analyticsName],
+ );
+
+ return (
+
+ {children}
+
+ );
+}
+
+type TriggerRenderState = {
+ hasMore: boolean;
+ loading: boolean;
+ disabled: boolean;
+};
+
+type TriggerRenderProp = useRender.RenderProp;
+
+export interface LoadMoreTriggerProps
+ extends Omit {
+ /**
+ * Override the auto-derived disabled state (`!hasMore || loading`). Pass
+ * `false` to force-enable; pass `true` to force-disable.
+ */
+ disabled?: boolean;
+ /**
+ * Replace the default `Button` element. Receives the merged click/disabled
+ * props the trigger would otherwise pass to `Button`.
+ */
+ render?: TriggerRenderProp;
+ /** Visible label. Defaults to `"Load more"`. */
+ children?: React.ReactNode;
+}
+
+interface RenderTriggerProps {
+ render: TriggerRenderProp;
+ state: TriggerRenderState;
+ forwardedProps: Record;
+ onClick: (event: React.MouseEvent) => void;
+ isDisabled: boolean;
+ loading: boolean;
+ forwardedRef: React.ForwardedRef;
+}
+
+function RenderTrigger({
+ render,
+ state,
+ forwardedProps,
+ onClick,
+ isDisabled,
+ loading,
+ forwardedRef,
+}: RenderTriggerProps) {
+ const internalProps = {
+ onClick,
+ disabled: isDisabled,
+ "aria-busy": loading || undefined,
+ "data-loading": loading || undefined,
+ "data-has-more": state.hasMore || undefined,
+ "data-disabled": isDisabled || undefined,
+ } as React.ComponentPropsWithRef<"button">;
+ return useRender({
+ render,
+ ref: forwardedRef as React.Ref,
+ state,
+ props: mergeProps<"button">(
+ internalProps,
+ forwardedProps as React.ComponentPropsWithRef<"button">,
+ ),
+ });
+}
+
+/** Manual button trigger. Defaults to Origin's `Button`. */
+export const LoadMoreTrigger = React.forwardRef<
+ HTMLButtonElement,
+ LoadMoreTriggerProps
+>(function LoadMoreTrigger(props, forwardedRef) {
+ const { disabled, render, children = "Load more", ...rest } = props;
+ const { hasMore, loading, onLoadMore, analyticsName } = useLoadMoreContext();
+ const isDisabled = disabled ?? (!hasMore || loading);
+
+ const handleClick = useTrackedCallback(
+ analyticsName,
+ "LoadMore",
+ "click",
+ () => {
+ if (isDisabled) return;
+ onLoadMore();
+ },
+ () => ({ part: "trigger" }),
+ );
+
+ if (render) {
+ return (
+ }
+ onClick={handleClick}
+ isDisabled={isDisabled}
+ loading={loading}
+ forwardedRef={forwardedRef}
+ />
+ );
+ }
+
+ return (
+
+ {children}
+
+ );
+});
+
+export interface LoadMoreSentinelProps
+ extends React.HTMLAttributes {
+ /**
+ * IntersectionObserver root. Defaults to the viewport. Pass a scroll
+ * container to scope observations to a scrolling region.
+ */
+ root?: Element | Document | null;
+ /** Defaults to `"0px 0px 200px 0px"` — preload 200px before reaching the sentinel. */
+ rootMargin?: string;
+ /** Defaults to `0`. */
+ threshold?: number | number[];
+ /**
+ * Disable the observer entirely. When `true` no DOM is rendered, so callers
+ * can fall back to a manual `Trigger`.
+ */
+ disabled?: boolean;
+ /** Override the rendered element. */
+ render?: useRender.RenderProp<{ hasMore: boolean; loading: boolean }>;
+}
+
+/** Invisible viewport-intersection trigger for infinite scroll. */
+export const LoadMoreSentinel = React.forwardRef<
+ HTMLDivElement,
+ LoadMoreSentinelProps
+>(function LoadMoreSentinel(props, forwardedRef) {
+ const {
+ root = null,
+ rootMargin = "0px 0px 200px 0px",
+ threshold = 0,
+ disabled,
+ render,
+ className,
+ ...rest
+ } = props;
+ const { hasMore, loading, onLoadMore, analyticsName } = useLoadMoreContext();
+
+ const onLoadMoreRef = React.useRef(onLoadMore);
+ onLoadMoreRef.current = onLoadMore;
+ const loadingRef = React.useRef(loading);
+ loadingRef.current = loading;
+ const hasMoreRef = React.useRef(hasMore);
+ hasMoreRef.current = hasMore;
+
+ const trackedIntersect = useTrackedCallback(
+ analyticsName,
+ "LoadMore",
+ "intersect",
+ () => onLoadMoreRef.current(),
+ () => ({ part: "sentinel" }),
+ );
+
+ const isMountedRef = React.useRef(false);
+
+ const localRef = React.useRef(null);
+ const setRef = React.useCallback(
+ (node: HTMLDivElement | null) => {
+ localRef.current = node;
+ if (typeof forwardedRef === "function") {
+ forwardedRef(node);
+ } else if (forwardedRef) {
+ forwardedRef.current = node;
+ }
+ },
+ [forwardedRef],
+ );
+
+ React.useEffect(() => {
+ if (disabled) return;
+ const node = localRef.current;
+ if (!node || typeof IntersectionObserver === "undefined") return;
+
+ const observer = new IntersectionObserver(
+ (entries) => {
+ for (const entry of entries) {
+ if (!entry.isIntersecting) continue;
+ if (loadingRef.current) continue;
+ if (!hasMoreRef.current) continue;
+ trackedIntersect();
+ break;
+ }
+ },
+ { root: root ?? null, rootMargin, threshold },
+ );
+
+ observer.observe(node);
+ return () => observer.disconnect();
+ }, [disabled, root, rootMargin, threshold, trackedIntersect]);
+
+ // After loading flips false, re-evaluate intersection in case the new page
+ // didn't grow tall enough to scroll the sentinel out of view. Skipped on
+ // initial mount so we don't double-fire alongside the IntersectionObserver
+ // setup effect when the sentinel is already in view.
+ React.useEffect(() => {
+ if (!isMountedRef.current) {
+ isMountedRef.current = true;
+ return;
+ }
+ if (loading || !hasMore || disabled) return;
+ const node = localRef.current;
+ if (!node || typeof window === "undefined") return;
+ const rect = node.getBoundingClientRect();
+ const inView = rect.top < window.innerHeight && rect.bottom > 0;
+ if (inView) trackedIntersect();
+ }, [loading, hasMore, disabled, trackedIntersect]);
+
+ if (disabled) return null;
+
+ const baseProps = {
+ "aria-hidden": true as const,
+ role: "presentation" as const,
+ "data-loading": loading || undefined,
+ "data-active": (hasMore && !loading) || undefined,
+ className: [styles.sentinel, className].filter(Boolean).join(" "),
+ };
+
+ if (render) {
+ return (
+ }
+ setRef={setRef}
+ />
+ );
+ }
+
+ return
;
+});
+
+interface RenderSentinelProps {
+ render: useRender.RenderProp<{ hasMore: boolean; loading: boolean }>;
+ state: { hasMore: boolean; loading: boolean };
+ baseProps: Record;
+ forwardedProps: Record;
+ setRef: React.RefCallback;
+}
+
+function RenderSentinel({
+ render,
+ state,
+ baseProps,
+ forwardedProps,
+ setRef,
+}: RenderSentinelProps) {
+ return useRender({
+ render,
+ ref: setRef,
+ state,
+ props: mergeProps<"div">(
+ baseProps as React.ComponentPropsWithRef<"div">,
+ forwardedProps as React.ComponentPropsWithRef<"div">,
+ ),
+ });
+}
+
+type StatusRenderState = { loading: boolean; hasMore: boolean };
+
+export interface LoadMoreStatusProps
+ extends Omit, "children"> {
+ /**
+ * Either static content, or a render function that receives the current
+ * load state and returns the announcement text.
+ */
+ children?: React.ReactNode | ((state: StatusRenderState) => React.ReactNode);
+ /** Defaults to `"polite"`. */
+ "aria-live"?: "polite" | "assertive" | "off";
+ render?: useRender.RenderProp<{ hasMore: boolean; loading: boolean }>;
+}
+
+/** SR-only `aria-live` announcement slot. */
+export const LoadMoreStatus = React.forwardRef<
+ HTMLDivElement,
+ LoadMoreStatusProps
+>(function LoadMoreStatus(props, forwardedRef) {
+ const {
+ children,
+ "aria-live": ariaLive = "polite",
+ render,
+ className,
+ ...rest
+ } = props;
+ const { hasMore, loading } = useLoadMoreContext();
+
+ const content =
+ typeof children === "function"
+ ? (children as (state: StatusRenderState) => React.ReactNode)({
+ loading,
+ hasMore,
+ })
+ : children;
+
+ const baseProps = {
+ "aria-live": ariaLive,
+ "aria-atomic": true as const,
+ "data-loading": loading || undefined,
+ "data-end": !hasMore || undefined,
+ className: [styles.status, className].filter(Boolean).join(" "),
+ };
+
+ if (render) {
+ return (
+
+ {content}
+
+ );
+});
+
+interface RenderStatusProps {
+ render: useRender.RenderProp<{ hasMore: boolean; loading: boolean }>;
+ state: { hasMore: boolean; loading: boolean };
+ baseProps: Record;
+ forwardedProps: Record;
+ forwardedRef: React.ForwardedRef;
+}
+
+function RenderStatus({
+ render,
+ state,
+ baseProps,
+ forwardedProps,
+ forwardedRef,
+}: RenderStatusProps) {
+ return useRender({
+ render,
+ ref: forwardedRef as React.Ref,
+ state,
+ props: mergeProps<"div">(
+ baseProps as React.ComponentPropsWithRef<"div">,
+ forwardedProps as React.ComponentPropsWithRef<"div">,
+ ),
+ });
+}
+
+if (process.env.NODE_ENV !== "production") {
+ LoadMoreTrigger.displayName = "LoadMoreTrigger";
+ LoadMoreSentinel.displayName = "LoadMoreSentinel";
+ LoadMoreStatus.displayName = "LoadMoreStatus";
+}
+
+export const LoadMore = {
+ Root: LoadMoreRoot,
+ Trigger: LoadMoreTrigger,
+ Sentinel: LoadMoreSentinel,
+ Status: LoadMoreStatus,
+};
+
+export default LoadMore;
diff --git a/packages/origin/src/components/LoadMore/LoadMore.unit.test.tsx b/packages/origin/src/components/LoadMore/LoadMore.unit.test.tsx
new file mode 100644
index 000000000..6f84630c5
--- /dev/null
+++ b/packages/origin/src/components/LoadMore/LoadMore.unit.test.tsx
@@ -0,0 +1,81 @@
+/**
+ * LoadMore Unit Tests (Vitest + @testing-library/react)
+ *
+ * For real browser testing (IntersectionObserver, scroll, accessibility),
+ * see LoadMore.test.tsx (Playwright CT).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render } from "@testing-library/react";
+import * as React from "react";
+import { LoadMore } from "./LoadMore";
+
+type ObserverCallback = (
+ entries: IntersectionObserverEntry[],
+ observer: IntersectionObserver,
+) => void;
+
+interface MockObserver {
+ observe: ReturnType;
+ unobserve: ReturnType;
+ disconnect: ReturnType;
+ takeRecords: ReturnType;
+ callback: ObserverCallback;
+}
+
+const observers: MockObserver[] = [];
+
+beforeEach(() => {
+ observers.length = 0;
+ class MockIntersectionObserver implements MockObserver {
+ callback: ObserverCallback;
+ observe = vi.fn();
+ unobserve = vi.fn();
+ disconnect = vi.fn();
+ takeRecords = vi.fn(() => []);
+
+ constructor(callback: ObserverCallback) {
+ this.callback = callback;
+ observers.push(this);
+ }
+ }
+ vi.stubGlobal("IntersectionObserver", MockIntersectionObserver);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+function fireIntersect(observer: MockObserver) {
+ const target = observer.observe.mock.calls[0]?.[0] as Element;
+ observer.callback(
+ [
+ {
+ isIntersecting: true,
+ target,
+ intersectionRatio: 1,
+ boundingClientRect: target.getBoundingClientRect(),
+ intersectionRect: target.getBoundingClientRect(),
+ rootBounds: null,
+ time: 0,
+ } as IntersectionObserverEntry,
+ ],
+ observer as unknown as IntersectionObserver,
+ );
+}
+
+describe("LoadMore.Sentinel initial mount", () => {
+ it("fires onLoadMore exactly once when the sentinel mounts already in view", () => {
+ const onLoadMore = vi.fn();
+ render(
+
+ ,
+ );
+
+ expect(observers).toHaveLength(1);
+ fireIntersect(observers[0]);
+
+ expect(onLoadMore).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/origin/src/components/LoadMore/index.ts b/packages/origin/src/components/LoadMore/index.ts
new file mode 100644
index 000000000..26baa0074
--- /dev/null
+++ b/packages/origin/src/components/LoadMore/index.ts
@@ -0,0 +1,14 @@
+export { LoadMore, useLoadMoreContext } from "./LoadMore";
+export type {
+ LoadMoreRootProps,
+ LoadMoreTriggerProps,
+ LoadMoreSentinelProps,
+ LoadMoreStatusProps,
+ LoadMoreContextValue,
+} from "./LoadMore";
+export { useLoadMore } from "./useLoadMore";
+export type {
+ UseLoadMoreOptions,
+ UseLoadMoreResult,
+ UseLoadMoreFetchResult,
+} from "./useLoadMore";
diff --git a/packages/origin/src/components/LoadMore/useLoadMore.ts b/packages/origin/src/components/LoadMore/useLoadMore.ts
new file mode 100644
index 000000000..a325d2a93
--- /dev/null
+++ b/packages/origin/src/components/LoadMore/useLoadMore.ts
@@ -0,0 +1,150 @@
+"use client";
+
+import * as React from "react";
+
+export interface UseLoadMoreFetchResult {
+ data: T[];
+ /** Cursor for the next page. Omit when there is no next page. */
+ nextCursor?: TCursor;
+ /** Whether `loadMore` should be enabled after this page. */
+ hasMore: boolean;
+}
+
+export interface UseLoadMoreOptions {
+ /**
+ * Fetches a page. Receives the cursor from the previous page, or `undefined`
+ * for the initial fetch (and after `refetch`/`resetOn` change). Reject the
+ * promise to surface an error in `result.error`.
+ */
+ fetchPage: (
+ cursor: TCursor | undefined,
+ ) => Promise>;
+ /**
+ * When any value changes (by `JSON.stringify` value), pagination resets and
+ * an initial fetch is kicked off. Values must be JSON-serializable; for
+ * object dependencies, pass a stable id. Defaults to `[]` (fetch once).
+ */
+ resetOn?: React.DependencyList;
+ /** Skip the initial fetch when `false`. Defaults to `true`. */
+ enabled?: boolean;
+ /** Starting cursor for the first page. */
+ initialCursor?: TCursor;
+}
+
+export interface UseLoadMoreResult {
+ items: T[];
+ /** True only during the initial fetch (and after refetch/reset). */
+ loading: boolean;
+ /** True only during subsequent (`loadMore`) fetches. */
+ loadingMore: boolean;
+ hasMore: boolean;
+ error: Error | undefined;
+ nextCursor: TCursor | undefined;
+ /** No-op when `!hasMore`, `loading`, or `loadingMore`. */
+ loadMore: () => void;
+ /** Resets accumulated items and re-fetches the first page. */
+ refetch: () => void;
+}
+
+/**
+ * Transport-agnostic infinite-scroll pagination state. Pair with
+ * `LoadMore.Sentinel` / `LoadMore.Trigger` to drive a forward-only paginated
+ * list. Stale responses are dropped via an internal request id so concurrent
+ * `refetch`/`resetOn` changes never clobber newer state.
+ */
+export function useLoadMore(
+ options: UseLoadMoreOptions,
+): UseLoadMoreResult {
+ const { fetchPage, resetOn, enabled = true, initialCursor } = options;
+
+ const [items, setItems] = React.useState([]);
+ const [loading, setLoading] = React.useState(enabled);
+ const [loadingMore, setLoadingMore] = React.useState(false);
+ const [error, setError] = React.useState(undefined);
+ const [nextCursor, setNextCursor] = React.useState