akanjs 2.3.11-rc.9 → 2.3.11

package/types/ui/Unauthorized.d.ts

@@ -1,9 +1,14 @@
 import type { ReactNode } from "react";
-interface UnauthorizedProps {
+export interface UnauthorizedProps {
     className?: string;
     description?: ReactNode;
     children?: ReactNode;
     minHeight?: number;
 }
-export declare const Unauthorized: ({ className, description, children, minHeight }: UnauthorizedProps) => import("react/jsx-runtime").JSX.Element;
-export {};
+export declare const DefaultUnauthorized: ({ className, description, children, minHeight }: UnauthorizedProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Unauthorized-state placeholder. Resolves to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one, otherwise
+ * renders {@link DefaultUnauthorized}.
+ */
+export declare const Unauthorized: import("react").ComponentType<UnauthorizedProps>;

package/types/ui/index.d.ts

@@ -41,4 +41,5 @@ export { System, type WebAppManifest } from "./System.d.ts";
 export { Tab } from "./Tab.d.ts";
 export { Table } from "./Table.d.ts";
 export { ToggleSelect } from "./ToggleSelect.d.ts";
+export { type AkanModalComponent, type AkanUiOverrideName, type AkanUiOverrides, createOverridable, override, UiOverrideProvider, type UiOverrideProviderProps, useUiOverride, } from "./UiOverride.d.ts";
 export { Unauthorized } from "./Unauthorized.d.ts";

package/ui/Button.tsx

@@ -1,9 +1,11 @@
 "use client";
 import { clsx, usePage } from "akanjs/client";
 import type React from "react";
-import { type ButtonHTMLAttributes, useState } from "react";
+import { type ButtonHTMLAttributes, type ComponentType, createElement, useState } from "react";
 import { AiOutlineCheckCircle } from "react-icons/ai";
 
+import { useUiOverride } from "./UiOverride";
+
 export type ButtonProps<Result> = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> & {
   /** Async-aware click handler. Call onError to show the localized error state without throwing. */
   onClick: (
@@ -14,7 +16,7 @@ export type ButtonProps<Result> = Omit<ButtonHTMLAttributes<HTMLButtonElement>,
   onSuccess?: (result: Result) => void;
 };
 
-export const Button = <Result = unknown>({ className, children, onClick, onSuccess, ...rest }: ButtonProps<Result>) => {
+const DefaultButton = <Result = unknown>({ className, children, onClick, onSuccess, ...rest }: ButtonProps<Result>) => {
   const { l } = usePage();
   const [state, setState] = useState<{
     mode: "idle" | "loading" | "success" | "error";
@@ -68,3 +70,14 @@ export const Button = <Result = unknown>({ className, children, onClick, onSucce
     </>
   );
 };
+
+/**
+ * Async-aware button. Resolves to a route-scoped override when a `page/**\/_overrides.tsx`
+ * in the route's ancestry declares one, otherwise renders {@link DefaultButton}. The public
+ * generic signature is preserved, so `<Button<Todo> onSuccess={(r: Todo) => …} />` still infers.
+ */
+export const Button = <Result = unknown>(props: ButtonProps<Result>) => {
+  const Override = useUiOverride("Button");
+  const Impl = (Override ?? DefaultButton) as unknown as ComponentType<ButtonProps<Result>>;
+  return createElement(Impl, props);
+};

package/ui/DatePicker.tsx

@@ -5,6 +5,8 @@ import { lazy } from "akanjs/webkit";
 import { type FocusEvent, useEffect, useRef } from "react";
 import { AiOutlineSwapRight } from "react-icons/ai";
 
+import { createOverridable } from "./UiOverride";
+
 const reactDatePickerPackage = "react-datepicker";
 const reactDatePickerStylePath = "react-datepicker/dist/react-datepicker.css";
 
@@ -15,7 +17,7 @@ const ReactDatePicker = lazy(
   },
   { ssr: false },
 );
-interface DatePickerProps {
+export interface DatePickerProps {
   value?: Dayjs | null;
   onChange: (value: Dayjs | null) => void;
   showTime?: boolean;
@@ -27,7 +29,7 @@ interface DatePickerProps {
   defaultValue?: Dayjs;
 }
 
-export const DatePicker = ({
+const DefaultDatePicker = ({
   value,
   onChange,
   showTime,
@@ -74,7 +76,7 @@ export const DatePicker = ({
   );
 };
 
-interface RangePickerProps {
+export interface RangePickerProps {
   value: [Dayjs | null, Dayjs | null];
   onChange: (value: [Dayjs | null, Dayjs | null]) => void;
   format?: string;
@@ -84,7 +86,7 @@ interface RangePickerProps {
   className?: string;
 }
 
-const RangePicker = ({
+const DefaultRangePicker = ({
   value,
   onChange,
   format = "yyyy-MM-dd",
@@ -143,9 +145,7 @@ const RangePicker = ({
   );
 };
 
-DatePicker.RangePicker = RangePicker;
-
-interface TimePickerProps {
+export interface TimePickerProps {
   value: Dayjs | null;
   onChange: (value: Dayjs) => void;
   format?: string;
@@ -155,7 +155,7 @@ interface TimePickerProps {
   disabled?: boolean;
 }
 
-const TimePicker = ({
+const DefaultTimePicker = ({
   disabled,
   className,
   value,
@@ -187,5 +187,15 @@ const TimePicker = ({
   );
 };
 
-DatePicker.TimePicker = TimePicker;
+const DatePickerBase = createOverridable("DatePicker", DefaultDatePicker);
+
+/**
+ * Date picker. `DatePicker`, `DatePicker.RangePicker`, and `DatePicker.TimePicker` each resolve to a
+ * route-scoped override when a `page/**\/_overrides.tsx` in the route's ancestry declares one (slots
+ * `DatePicker`, `DatePickerRangePicker`, `DatePickerTimePicker`).
+ */
+export const DatePicker = Object.assign(DatePickerBase, {
+  RangePicker: createOverridable("DatePickerRangePicker", DefaultRangePicker),
+  TimePicker: createOverridable("DatePickerTimePicker", DefaultTimePicker),
+});
 

package/ui/Dropdown.tsx

@@ -2,6 +2,8 @@
 import { clsx } from "akanjs/client";
 import { type ReactNode, useState } from "react";
 
+import { createOverridable } from "./UiOverride";
+
 export interface DropdownProps {
   /** Button/trigger content. */
   value: ReactNode;
@@ -15,7 +17,7 @@ export interface DropdownProps {
   dropdownClassName?: string;
 }
 
-export const Dropdown = ({ value, content, className, buttonClassName, dropdownClassName }: DropdownProps) => {
+export const DefaultDropdown = ({ value, content, className, buttonClassName, dropdownClassName }: DropdownProps) => {
   const [opened, setOpened] = useState(false);
   return (
     <div
@@ -49,3 +51,9 @@ export const Dropdown = ({ value, content, className, buttonClassName, dropdownC
     </div>
   );
 };
+
+/**
+ * Dropdown. Resolves to a route-scoped override when a `page/**\/_overrides.tsx`
+ * in the route's ancestry declares one, otherwise renders {@link DefaultDropdown}.
+ */
+export const Dropdown = createOverridable("Dropdown", DefaultDropdown);

package/ui/Empty.tsx

@@ -1,7 +1,10 @@
+"use client";
 import { clsx, usePage } from "akanjs/client";
 import type { ReactNode } from "react";
 import { AiOutlineMeh } from "react-icons/ai";
 
+import { createOverridable } from "./UiOverride";
+
 export interface EmptyProps {
   /** Additional classes for the empty-state body. */
   className?: string;
@@ -13,7 +16,7 @@ export interface EmptyProps {
   minHeight?: number;
 }
 
-export const Empty = ({ className = "", description, children, minHeight = 300 }: EmptyProps) => {
+export const DefaultEmpty = ({ className = "", description, children, minHeight = 300 }: EmptyProps) => {
   const { l } = usePage();
   return (
     <div>
@@ -30,3 +33,10 @@ export const Empty = ({ className = "", description, children, minHeight = 300 }
     </div>
   );
 };
+
+/**
+ * Empty-state placeholder. Resolves to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one, otherwise
+ * renders {@link DefaultEmpty}.
+ */
+export const Empty = createOverridable("Empty", DefaultEmpty);

package/ui/Input.tsx

@@ -13,6 +13,8 @@ import React, {
 } from "react";
 import { AiOutlineEye, AiOutlineEyeInvisible } from "react-icons/ai";
 
+import { createOverridable } from "./UiOverride";
+
 export type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "onChange"> & {
   /** Visual input style. */
   inputStyleType?: "bordered" | "borderless" | "underline";
@@ -38,7 +40,7 @@ export type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "
   /** Called when Escape is pressed after blurring the input. */
   onPressEscape?: (e: KeyboardEvent<HTMLInputElement>) => void;
 };
-export const Input = ({
+const DefaultInput = ({
   className,
   nullable,
   inputRef,
@@ -145,7 +147,7 @@ export type TextAreaProps = Omit<
   validate: (value: string) => boolean | string;
   onPressEscape?: (e: KeyboardEvent<HTMLTextAreaElement>) => void;
 };
-const TextArea = ({
+const DefaultTextArea = ({
   className,
   nullable,
   value,
@@ -218,7 +220,6 @@ const TextArea = ({
     </div>
   );
 };
-Input.TextArea = TextArea;
 
 export type PasswordProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "type" | "onChange"> & {
   value: string;
@@ -233,7 +234,7 @@ export type PasswordProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value"
   onChange?: (value: string, e?: ChangeEvent<HTMLInputElement>) => void;
   validate: (value: string) => boolean | string;
 };
-const Password = ({
+const DefaultPassword = ({
   className,
   nullable,
   value,
@@ -330,8 +331,6 @@ const Password = ({
   );
 };
 
-Input.Password = Password;
-
 export type EmailProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "type" | "onChange"> & {
   inputStyleType?: "bordered" | "borderless" | "underline";
   value: string;
@@ -346,7 +345,7 @@ export type EmailProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "
   onChange?: (value: string, e?: ChangeEvent<HTMLInputElement>) => void;
   validate: (value: string) => boolean | string;
 };
-const Email = ({
+const DefaultEmail = ({
   inputStyleType = "bordered",
   className,
   nullable,
@@ -445,8 +444,6 @@ const Email = ({
   );
 };
 
-Input.Email = Email;
-
 export type NumberProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "type" | "onChange"> & {
   value: number | null;
   nullable?: boolean;
@@ -464,7 +461,7 @@ export type NumberProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" |
   formatter?: (value: string) => string;
   parser?: (value: string) => string;
 };
-const Number = ({
+const DefaultNumber = ({
   className,
   nullable,
   value,
@@ -612,15 +609,13 @@ const Number = ({
   );
 };
 
-Input.Number = Number;
-
 export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "onChange"> & {
   className?: string;
   checked: boolean;
   onChange: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void;
 };
 
-const Checkbox = ({ checked, onChange, className, ...rest }: CheckboxProps) => {
+const DefaultCheckbox = ({ checked, onChange, className, ...rest }: CheckboxProps) => {
   return (
     <input
       {...rest}
@@ -633,4 +628,17 @@ const Checkbox = ({ checked, onChange, className, ...rest }: CheckboxProps) => {
     />
   );
 };
-Input.Checkbox = Checkbox;
+const InputBase = createOverridable("Input", DefaultInput);
+
+/**
+ * Text input plus its field variants. Each leaf resolves to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `Input`, `InputTextArea`,
+ * `InputPassword`, `InputEmail`, `InputNumber`, `InputCheckbox`), otherwise renders the default.
+ */
+export const Input = Object.assign(InputBase, {
+  TextArea: createOverridable("InputTextArea", DefaultTextArea),
+  Password: createOverridable("InputPassword", DefaultPassword),
+  Email: createOverridable("InputEmail", DefaultEmail),
+  Number: createOverridable("InputNumber", DefaultNumber),
+  Checkbox: createOverridable("InputCheckbox", DefaultCheckbox),
+});

package/ui/Loading/index.tsx

@@ -1,3 +1,5 @@
+"use client";
+import { createOverridable } from "../UiOverride";
 import { Area } from "./Area";
 import { Button } from "./Button";
 import { Input } from "./Input";
@@ -5,4 +7,16 @@ import { ProgressBar } from "./ProgressBar";
 import { Skeleton } from "./Skeleton";
 import { Spin } from "./Spin";
 
-export const Loading = { Area, Button, Input, ProgressBar, Skeleton, Spin };
+/**
+ * Loading indicators. Each member is an independent override slot (`LoadingSpin`, `LoadingSkeleton`,
+ * `LoadingProgressBar`, `LoadingButton`, `LoadingInput`, `LoadingArea`), resolved from the closest
+ * `page/**\/_overrides.tsx` in the route's ancestry, otherwise the shipped default.
+ */
+export const Loading = {
+  Area: createOverridable("LoadingArea", Area),
+  Button: createOverridable("LoadingButton", Button),
+  Input: createOverridable("LoadingInput", Input),
+  ProgressBar: createOverridable("LoadingProgressBar", ProgressBar),
+  Skeleton: createOverridable("LoadingSkeleton", Skeleton),
+  Spin: createOverridable("LoadingSpin", Spin),
+};

package/ui/Menu.tsx

@@ -4,7 +4,9 @@ import { st } from "akanjs/store";
 import { type ReactNode, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { AiFillCaretDown, AiOutlineEllipsis } from "react-icons/ai";
 
-interface MenuItem {
+import { createOverridable } from "./UiOverride";
+
+export interface MenuItem {
   label: ReactNode;
   key: string;
   children?: MenuItem[];
@@ -12,7 +14,7 @@ interface MenuItem {
   type?: string;
 }
 
-interface MenuProps {
+export interface MenuProps {
   className?: string;
   ulClassName?: string;
   liClassName?: string;
@@ -29,7 +31,7 @@ interface MenuProps {
   onMouseLeave?: () => void;
 }
 
-export const Menu = ({
+export const DefaultMenu = ({
   items,
   onClick,
   selectedKeys,
@@ -271,3 +273,10 @@ const OverflowMenu = ({ overflowItems, onClick }: OverflowMenuProps) => {
     </li>
   );
 };
+
+/**
+ * Navigation menu. Resolves to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one, otherwise
+ * renders {@link DefaultMenu}.
+ */
+export const Menu = createOverridable("Menu", DefaultMenu);

package/ui/Modal.tsx

@@ -2,6 +2,7 @@
 import type { ReactNode } from "react";
 
 import { Dialog } from "./Dialog";
+import { createOverridable } from "./UiOverride";
 
 export interface ModalProps {
   /** Additional classes for the modal surface. */
@@ -21,7 +22,11 @@ export interface ModalProps {
   confirmClose?: boolean;
 }
 
-export const Modal = ({
+/**
+ * Default akanjs modal skin. Kept as the fallback implementation; apps replace
+ * it per-route through a `page/**\/_overrides.tsx` manifest.
+ */
+export const DefaultModal = ({
   className,
   title,
   action,
@@ -41,3 +46,10 @@ export const Modal = ({
     </Dialog>
   );
 };
+
+/**
+ * Public Modal. Resolves to a route-scoped override when a `_overrides.tsx` in
+ * the route's ancestry declares one, otherwise renders {@link DefaultModal}.
+ * The proxy is transparent to every existing `<Modal … />` call site.
+ */
+export const Modal = createOverridable("Modal", DefaultModal);

package/ui/Pagination.tsx

@@ -3,6 +3,8 @@ import { clsx } from "akanjs/client";
 import type { FC, ReactNode } from "react";
 import { BiChevronLeft, BiChevronRight, BiDotsHorizontalRounded } from "react-icons/bi";
 
+import { createOverridable } from "./UiOverride";
+
 export interface PaginationProps {
   /** Current 1-based page number. */
   currentPage: number;
@@ -22,7 +24,7 @@ export interface PaginationProps {
   };
 }
 
-export const Pagination: FC<PaginationProps> = ({
+export const DefaultPagination: FC<PaginationProps> = ({
   currentPage,
   total,
   onPageSelect,
@@ -118,3 +120,9 @@ export const Pagination: FC<PaginationProps> = ({
     </div>
   );
 };
+
+/**
+ * Pager. Resolves to a route-scoped override when a `page/**\/_overrides.tsx` in
+ * the route's ancestry declares one, otherwise renders {@link DefaultPagination}.
+ */
+export const Pagination = createOverridable("Pagination", DefaultPagination);

package/ui/Popconfirm.tsx

@@ -6,6 +6,7 @@ import { type ButtonHTMLAttributes, type ReactNode, useEffect, useState } from "
 import { BiMessageRoundedError } from "react-icons/bi";
 
 import { animated } from "./animated";
+import { createOverridable } from "./UiOverride";
 
 type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
   loading?: boolean;
@@ -34,7 +35,7 @@ export interface PopconfirmProps {
   decoClassName?: string;
 }
 
-export const Popconfirm = ({
+export const DefaultPopconfirm = ({
   title,
   description,
   onConfirm,
@@ -133,3 +134,10 @@ export const Popconfirm = ({
     </>
   );
 };
+
+/**
+ * Confirmation popover. Resolves to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one, otherwise
+ * renders {@link DefaultPopconfirm}.
+ */
+export const Popconfirm = createOverridable("Popconfirm", DefaultPopconfirm);

package/ui/Radio.tsx

@@ -2,6 +2,8 @@
 import { clsx } from "akanjs/client";
 import type { ReactElement, ReactNode } from "react";
 
+import { createOverridable } from "./UiOverride";
+
 export interface RadioProps {
   value: string | number | null;
   className?: string;
@@ -9,7 +11,7 @@ export interface RadioProps {
   children: ReactNode | ReactElement | ReactElement[];
   onChange: (value: string | number | null, idx: number) => void;
 }
-export const Radio = ({ value, children, disabled, className, onChange }: RadioProps) => {
+const DefaultRadio = ({ value, children, disabled, className, onChange }: RadioProps) => {
   return (
     <div className={clsx(`flex gap-2`, className)}>
       {(children as ReactElement<{ value: string | number | null }>[]).map((child, idx) => {
@@ -47,7 +49,16 @@ export interface ItemProps {
   onChange?: (value: string) => void;
 }
 
-const Item = ({ value, className, children }: ItemProps) => {
+const DefaultItem = ({ value, className, children }: ItemProps) => {
   return <div className={clsx("", className)}>{children}</div>;
 };
-Radio.Item = Item;
+
+const RadioBase = createOverridable("Radio", DefaultRadio);
+
+/**
+ * Radio group. `Radio` and `Radio.Item` each resolve to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `Radio`, `RadioItem`).
+ */
+export const Radio = Object.assign(RadioBase, {
+  Item: createOverridable("RadioItem", DefaultItem),
+});

package/ui/Select.tsx

@@ -2,11 +2,13 @@
 import { type Cls, type EnumInstance, isEnum } from "akanjs/base";
 import { clsx, usePage } from "akanjs/client";
 import { useDebounce } from "akanjs/webkit";
-import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import { type ComponentType, createElement, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import { BiCheck, BiChevronDown, BiX } from "react-icons/bi";
 import { BsQuestionCircleFill } from "react-icons/bs";
 import { TiDelete } from "react-icons/ti";
 
+import { useUiOverride } from "./UiOverride";
+
 interface LabelOption<T> {
   label: string | boolean | number;
   value: T;
@@ -53,7 +55,7 @@ export interface SelectProps<
   renderSelected?: (value: T) => ReactNode;
 }
 
-export const Select = <
+const DefaultSelect = <
   T extends string | number | boolean | null | undefined,
   Multiple extends boolean = false,
   Searchable extends boolean = false,
@@ -320,3 +322,21 @@ export const Select = <
     </div>
   );
 };
+
+/**
+ * Select. Resolves to a route-scoped override when a `page/**\/_overrides.tsx` in the route's
+ * ancestry declares one, otherwise renders {@link DefaultSelect}. The public generic signature is
+ * preserved, so `<Select<MyEnum, true> …/>` still infers the value/onChange shape.
+ */
+export const Select = <
+  T extends string | number | boolean | null | undefined,
+  Multiple extends boolean = false,
+  Searchable extends boolean = false,
+  Option extends Options<T> = Options<T>,
+>(
+  props: SelectProps<T, Multiple, Searchable, Option>,
+) => {
+  const Override = useUiOverride("Select");
+  const Impl = (Override ?? DefaultSelect) as unknown as ComponentType<SelectProps<T, Multiple, Searchable, Option>>;
+  return createElement(Impl, props);
+};

package/ui/Table.tsx

@@ -8,6 +8,7 @@ import { AiOutlineLoading3Quarters } from "react-icons/ai";
 
 import { Empty } from "./Empty";
 import { Pagination, type PaginationProps } from "./Pagination";
+import { createOverridable } from "./UiOverride";
 
 export interface Column {
   /** Stable column key. Defaults to index when omitted. */
@@ -45,7 +46,7 @@ export interface TableProps {
   rowKey?: (model: any) => string;
 }
 
-export const Table = ({
+export const DefaultTable = ({
   columns,
   dataSource,
   loading,
@@ -129,3 +130,9 @@ export const Table = ({
     </div>
   );
 };
+
+/**
+ * Data table. Resolves to a route-scoped override when a `page/**\/_overrides.tsx`
+ * in the route's ancestry declares one, otherwise renders {@link DefaultTable}.
+ */
+export const Table = createOverridable("Table", DefaultTable);

package/ui/ToggleSelect.tsx

@@ -1,6 +1,10 @@
+"use client";
 import { clsx, usePage } from "akanjs/client";
+import { type ComponentType, createElement } from "react";
 
-interface ToggleSelectProps<I extends string | number | boolean | null> {
+import { createOverridable, useUiOverride } from "./UiOverride";
+
+export interface ToggleSelectProps<I extends string | number | boolean | null> {
   className?: string;
   btnClassName?: string;
   items: string[] | number[] | { label: string; value: I; disabled?: boolean }[];
@@ -10,7 +14,7 @@ interface ToggleSelectProps<I extends string | number | boolean | null> {
   onChange: (value: I, idx: number) => void;
   disabled?: boolean;
 }
-export const ToggleSelect = <I extends string | number | boolean | null>({
+const DefaultToggleSelect = <I extends string | number | boolean | null>({
   className,
   btnClassName,
   items,
@@ -72,7 +76,7 @@ export const ToggleSelect = <I extends string | number | boolean | null>({
   );
 };
 
-interface MultiProps {
+export interface MultiProps {
   className?: string;
   btnClassName?: string;
   items: string[] | number[] | { label: string; value: string | number; disabled?: boolean }[];
@@ -82,7 +86,16 @@ interface MultiProps {
   onChange: (value: string[] | number[]) => void;
   disabled?: boolean;
 }
-const Multi = ({ className, btnClassName, items, nullable, validate, value, onChange, disabled }: MultiProps) => {
+const DefaultMulti = ({
+  className,
+  btnClassName,
+  items,
+  nullable,
+  validate,
+  value,
+  onChange,
+  disabled,
+}: MultiProps) => {
   const { l } = usePage();
   const validateResult = validate(value);
 
@@ -141,4 +154,17 @@ const Multi = ({ className, btnClassName, items, nullable, validate, value, onCh
     </div>
   );
 };
-ToggleSelect.Multi = Multi;
+const ToggleSelectBase = <I extends string | number | boolean | null>(props: ToggleSelectProps<I>) => {
+  const Override = useUiOverride("ToggleSelect");
+  const Impl = (Override ?? DefaultToggleSelect) as unknown as ComponentType<ToggleSelectProps<I>>;
+  return createElement(Impl, props);
+};
+
+/**
+ * Toggle-select. `ToggleSelect` keeps its generic signature (so `<ToggleSelect<Status> …/>` still
+ * infers), and both it and `ToggleSelect.Multi` resolve to a route-scoped override when a
+ * `page/**\/_overrides.tsx` in the route's ancestry declares one (slots `ToggleSelect`, `ToggleSelectMulti`).
+ */
+export const ToggleSelect = Object.assign(ToggleSelectBase, {
+  Multi: createOverridable("ToggleSelectMulti", DefaultMulti),
+});

package/ui/UiOverride/Provider.tsx

@@ -0,0 +1,22 @@
+"use client";
+import { type ReactNode, useContext, useMemo } from "react";
+
+import { type AkanUiOverrides, UiOverrideContext } from "./context";
+
+export interface UiOverrideProviderProps {
+  /** Override map for this subtree; merged over any ancestor overrides. */
+  value?: Partial<AkanUiOverrides>;
+  children?: ReactNode;
+}
+
+/**
+ * Supplies route-scoped UI overrides. Merges its own `value` over the overrides
+ * inherited from ancestors so the closest declaration wins, matching nested
+ * `_overrides.tsx` resolution. `routeTreeBuilder` mounts one of these per route
+ * node once the `_overrides.tsx` convention is wired.
+ */
+export const UiOverrideProvider = ({ value, children }: UiOverrideProviderProps) => {
+  const parent = useContext(UiOverrideContext);
+  const merged = useMemo(() => ({ ...parent, ...value }), [parent, value]);
+  return <UiOverrideContext.Provider value={merged}>{children}</UiOverrideContext.Provider>;
+};