akanjs 2.3.11-rc.9 → 2.3.11

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # akanjs
 
+## 2.3.11
+
+### Minor Changes
+
+- 595390a: feat: UiOverride 시스템 및 \_overrides.tsx 지원 추가
+
+  - `akanjs/ui/UiOverride` 추가: `Provider`, `createOverridable`, `useUiOverride`, `override` API로 UI 컴포넌트 커스터마이징 지원
+  - 모든 akanjs UI 컴포넌트(Button, Modal, Select, Table 등)에 `useUiOverride()` 통합
+  - 라우트 시스템에 `_overrides.tsx` 지원 추가 (routeConvention, routeTreeBuilder)
+  - qualityScanner에 `_overrides.tsx` 파일 검증 로직 추가
+  - 앱 예제: `apps/minimal`에 `_overrides.tsx`, `BrandModal`, `OverrideDemo` 추가
+  - `apps/akan` 문서에 UI 커스터마이징 가이드 페이지 추가
+  - devkit에 `no-throw-raw-error.grit` lint rule 추가
+  - `PushNotificationServer.ts` 리팩토링
+  - biome.json 업데이트 및 패키지 의존성 정리
+
+### Patch Changes
+
+- 5ce752a: enhance: add host option for staging server tests
+- 5ce752a: add host option for staging server tests
+
 ## 2.3.10
 
 ### Patch Changes

package/client/csrTypes.ts

@@ -191,6 +191,8 @@ export interface Route {
   path: string;
   renderPage?: RouteRender;
   renderLayout?: RouteRender;
+  /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
+  renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;
   isSpecialRoute?: boolean;
 

package/common/routeConvention.ts

@@ -1,11 +1,13 @@
 const ROUTE_SOURCE_RE = /^\.\/(.+)\.(tsx|ts|jsx|js)$/;
 const SOURCE_EXT_RE = /\.(tsx|ts|jsx|js)$/;
-const RESERVED_ROUTE_FILES = new Set(["_layout", "_index"]);
+const RESERVED_ROUTE_FILES = new Set(["_layout", "_index", "_overrides"]);
 const INTERNAL_ROOT_LAYOUT_LEAF = "__root_layout";
 const IMPLICIT_LOCALE_SEGMENT = "[lang]";
 const SPECIAL_ROUTE_LEAVES = new Set(["robots.txt"]);
 
-export type RouteModuleKind = "page" | "layout";
+const DIRECTORY_SCOPED_LEAVES = new Set(["_layout", "_index", "_overrides"]);
+
+export type RouteModuleKind = "page" | "layout" | "overrides";
 
 export interface ParsedRouteModuleKey {
   key: string;
@@ -51,7 +53,7 @@ export function validatePageSourceFile(filePath: string, options: ValidatePageSo
   if (ext !== "tsx") throw new Error(`[route-convention] route source files under page/ must use .tsx: ${displayPath}`);
   if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && leaf !== INTERNAL_ROOT_LAYOUT_LEAF)
     throw new Error(
-      `[route-convention] only _index.tsx and _layout.tsx are allowed as reserved route files under page/: ${displayPath}`,
+      `[route-convention] only _index.tsx, _layout.tsx and _overrides.tsx are allowed as reserved route files under page/: ${displayPath}`,
     );
   if (/^[A-Z]/.test(leaf))
     throw new Error(`[route-convention] route page filenames must not start with an uppercase letter: ${displayPath}`);
@@ -97,13 +99,14 @@ export function parseRouteModuleKey(key: string): ParsedRouteModuleKey {
   }
 
   const isInternalRootLayout = leaf === INTERNAL_ROOT_LAYOUT_LEAF;
-  const kind: RouteModuleKind = leaf === "_layout" || isInternalRootLayout ? "layout" : "page";
+  const kind: RouteModuleKind =
+    leaf === "_layout" || isInternalRootLayout ? "layout" : leaf === "_overrides" ? "overrides" : "page";
   if (leaf.startsWith("_") && !RESERVED_ROUTE_FILES.has(leaf) && !isInternalRootLayout) {
     throw new Error(`[route-convention] unsupported reserved route file "${leaf}" in ${key}`);
   }
 
   const sourceRouteSegments =
-    leaf === "_layout" || leaf === "_index" || isInternalRootLayout ? moduleSegments.slice(0, -1) : moduleSegments;
+    DIRECTORY_SCOPED_LEAVES.has(leaf) || isInternalRootLayout ? moduleSegments.slice(0, -1) : moduleSegments;
   const isSpecialRoute = kind === "page" && SPECIAL_ROUTE_LEAVES.has(leaf);
   const routeSegments = isSpecialRoute ? sourceRouteSegments : [IMPLICIT_LOCALE_SEGMENT, ...sourceRouteSegments];
   for (const segment of routeSegments) validateRouteSegment(segment, key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.3.11-rc.9",
+  "version": "2.3.11",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/routeTreeBuilder.ts

@@ -18,9 +18,12 @@ import {
   parseRouteModuleKey,
   routeSegmentToTreePath,
 } from "akanjs/common";
+import { createElement } from "react";
 import { validatePageConfig } from "../client/frameConfig";
 import { resolveHeadExport, resolveMetadataHead } from "./metadata";
 
+type RouteModuleKindWithOverrides = "page" | "layout" | "overrides";
+
 export type PagesContext = Record<string, () => Promise<RouteModule>>;
 
 export const defaultPageState: PageState = {
@@ -197,6 +200,14 @@ export class RouteTreeBuilder {
     const targetPath = pathSegments[pathSegments.length - 1];
     if (!targetPath) return;
 
+    if (parsed.kind === "overrides") {
+      targetRouteMap.set(targetPath, {
+        ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
+        renderOverrides: this.#makeOverridesRender(filePath, loader),
+      } as Route);
+      return;
+    }
+
     const routeRender = RouteTreeBuilder.#makeRouteRender(filePath, parsed.kind, loader);
     targetRouteMap.set(targetPath, {
       ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
@@ -224,8 +235,10 @@ export class RouteTreeBuilder {
     const pathSegments = [...parentPaths, ...(currentPathSegment ? [currentPathSegment] : [])];
     const currentRootLayout = isRoot && route.renderLayout ? route.renderLayout : null;
     const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
+
+    const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
     const renderRootLayouts = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
+    const renderLayouts = [...parentLayouts, ...currentOverrideRenders, ...(currentLayout ? [currentLayout] : [])];
     if (route.renderLayout) {
       this.#fallbackRoutes.push({
         path: routePath,
@@ -237,7 +250,10 @@ export class RouteTreeBuilder {
     const routeHead = RouteTreeBuilder.#composeHeadResolvers(route.renderLayout?.resolveHead, parentHead);
     const pageRenderRootLayouts =
       route.pageIncludesOwnLayout === false && currentRootLayout ? parentRootLayouts : renderRootLayouts;
-    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
+    const pageRenderLayouts =
+      route.pageIncludesOwnLayout === false && currentLayout
+        ? [...parentLayouts, ...currentOverrideRenders]
+        : renderLayouts;
     const pageHead = route.pageIncludesOwnLayout === false ? parentHead : routeHead;
     return [
       ...(route.renderPage
@@ -262,7 +278,7 @@ export class RouteTreeBuilder {
     ];
   }
 
-  static #makeLazyModule(key: string, kind: "page" | "layout", loader: () => Promise<RouteModule>) {
+  static #makeLazyModule(key: string, kind: RouteModuleKindWithOverrides, loader: () => Promise<RouteModule>) {
     let cached: RouteModule | null = null;
     let loaded = false;
     RouteTreeBuilder.#moduleCacheStats.moduleCount += 1;
@@ -285,7 +301,12 @@ export class RouteTreeBuilder {
     };
   }
 
-  static #validateRouteModuleExports(key: string, kind: "page" | "layout", mod: RouteModule) {
+  static #validateRouteModuleExports(key: string, kind: RouteModuleKindWithOverrides, mod: RouteModule) {
+    if (kind === "overrides") {
+      
+      if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
+      return;
+    }
     const parsed = parseRouteModuleKey(key);
     const allowed =
       kind === "page"
@@ -378,6 +399,18 @@ export class RouteTreeBuilder {
     return routeRender;
   }
 
+  #makeOverridesRender(key: string, loader: () => Promise<RouteModule>): RouteRender {
+    const loadModule = RouteTreeBuilder.#makeLazyModule(key, "overrides", loader);
+    return {
+      isAsync: true,
+      render: (async ({ children }: LayoutProps) => {
+        const mod = await loadModule();
+        if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
+        return createElement(mod.default as never, { children } as never);
+      }) as RouteRender["render"],
+    };
+  }
+
   static #composeHeadResolvers(...resolvers: (ResolveHead | undefined)[]): ResolveHead | undefined {
     const chain = resolvers.filter((resolver): resolver is ResolveHead => Boolean(resolver));
     if (chain.length === 0) return undefined;

package/types/client/csrTypes.d.ts

@@ -190,6 +190,8 @@ export interface Route {
     path: string;
     renderPage?: RouteRender;
     renderLayout?: RouteRender;
+    /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
+    renderOverrides?: RouteRender;
     pageIncludesOwnLayout?: boolean;
     isSpecialRoute?: boolean;
     loader?: () => unknown;

package/types/common/routeConvention.d.ts

@@ -1,4 +1,4 @@
-export type RouteModuleKind = "page" | "layout";
+export type RouteModuleKind = "page" | "layout" | "overrides";
 export interface ParsedRouteModuleKey {
     key: string;
     kind: RouteModuleKind;

package/types/ui/Button.d.ts

@@ -8,4 +8,9 @@ export type ButtonProps<Result> = Omit<ButtonHTMLAttributes<HTMLButtonElement>,
     /** Called after the button briefly enters success state. */
     onSuccess?: (result: Result) => void;
 };
-export declare const Button: <Result = unknown>({ className, children, onClick, onSuccess, ...rest }: ButtonProps<Result>) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare const Button: <Result = unknown>(props: ButtonProps<Result>) => React.ReactElement<ButtonProps<Result>, string | React.JSXElementConstructor<any>>;

package/types/ui/DatePicker.d.ts

@@ -1,5 +1,5 @@
 import { type Dayjs } from "akanjs/base";
-interface DatePickerProps {
+export interface DatePickerProps {
     value?: Dayjs | null;
     onChange: (value: Dayjs | null) => void;
     showTime?: boolean;
@@ -10,12 +10,7 @@ interface DatePickerProps {
     placement?: "top" | "bottom" | "left" | "right";
     defaultValue?: Dayjs;
 }
-export declare const DatePicker: {
-    ({ value, onChange, showTime, format, timeIntervals, disabledDate, placement, className, defaultValue, }: DatePickerProps): import("react/jsx-runtime").JSX.Element;
-    RangePicker: ({ value, onChange, format, showTime, timeIntervals, disabledDate, className, }: RangePickerProps) => import("react/jsx-runtime").JSX.Element;
-    TimePicker: ({ disabled, className, value, format, onChange, timeIntervals, }: TimePickerProps) => import("react/jsx-runtime").JSX.Element;
-};
-interface RangePickerProps {
+export interface RangePickerProps {
     value: [Dayjs | null, Dayjs | null];
     onChange: (value: [Dayjs | null, Dayjs | null]) => void;
     format?: string;
@@ -24,7 +19,7 @@ interface RangePickerProps {
     disabledDate?: (date: Dayjs) => boolean | null | undefined;
     className?: string;
 }
-interface TimePickerProps {
+export interface TimePickerProps {
     value: Dayjs | null;
     onChange: (value: Dayjs) => void;
     format?: string;
@@ -33,4 +28,12 @@ interface TimePickerProps {
     className?: string;
     disabled?: boolean;
 }
-export {};
+/**
+ * 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 declare const DatePicker: import("react").ComponentType<DatePickerProps> & {
+    RangePicker: import("react").ComponentType<RangePickerProps>;
+    TimePicker: import("react").ComponentType<TimePickerProps>;
+};

package/types/ui/Dropdown.d.ts

@@ -11,4 +11,9 @@ export interface DropdownProps {
     /** Additional classes for the dropdown content panel. */
     dropdownClassName?: string;
 }
-export declare const Dropdown: ({ value, content, className, buttonClassName, dropdownClassName }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultDropdown: ({ value, content, className, buttonClassName, dropdownClassName }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Dropdown. Resolves to a route-scoped override when a `page/**\/_overrides.tsx`
+ * in the route's ancestry declares one, otherwise renders {@link DefaultDropdown}.
+ */
+export declare const Dropdown: import("react").ComponentType<DropdownProps>;

package/types/ui/Empty.d.ts

@@ -9,4 +9,10 @@ export interface EmptyProps {
     /** Minimum empty-state height in pixels. */
     minHeight?: number;
 }
-export declare const Empty: ({ className, description, children, minHeight }: EmptyProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultEmpty: ({ className, description, children, minHeight }: EmptyProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare const Empty: import("react").ComponentType<EmptyProps>;

package/types/ui/Input.d.ts

@@ -24,14 +24,6 @@ export type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "
     /** Called when Escape is pressed after blurring the input. */
     onPressEscape?: (e: KeyboardEvent<HTMLInputElement>) => void;
 };
-export declare const Input: {
-    ({ className, nullable, inputRef, value, cacheKey, inputStyleType, icon, iconClassName, inputClassName, inputWrapperClassName, onPressEnter, onPressEscape, onChange, validate, ...rest }: InputProps): import("react/jsx-runtime").JSX.Element;
-    TextArea: ({ className, nullable, value, inputClassName, inputWrapperClassName, cacheKey, onPressEnter, onPressEscape, onChange, validate, ...rest }: TextAreaProps) => import("react/jsx-runtime").JSX.Element;
-    Password: ({ className, nullable, value, icon, iconClassName, inputClassName, inputWrapperClassName, cacheKey, onPressEnter, onPressEscape, onChange, validate, ...rest }: PasswordProps) => import("react/jsx-runtime").JSX.Element;
-    Email: ({ inputStyleType, className, nullable, value, cacheKey, onPressEnter, onPressEscape, onChange, validate, icon, iconClassName, inputClassName, inputWrapperClassName, ...rest }: EmailProps) => import("react/jsx-runtime").JSX.Element;
-    Number: ({ className, nullable, value, icon, cacheKey, iconClassName, inputClassName, inputWrapperClassName, numberFormat, onPressEnter, onPressEscape, validate, onChange, formatter, parser, ...rest }: NumberProps) => import("react/jsx-runtime").JSX.Element;
-    Checkbox: ({ checked, onChange, className, ...rest }: CheckboxProps) => import("react/jsx-runtime").JSX.Element;
-};
 export type TextAreaProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "type" | "onChange" | "onPressEnter"> & {
     inputRef?: RefObject<HTMLTextAreaElement | null>;
     value: string;
@@ -93,3 +85,15 @@ export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "onChang
     checked: boolean;
     onChange: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void;
 };
+/**
+ * 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 declare const Input: React.ComponentType<InputProps> & {
+    TextArea: React.ComponentType<TextAreaProps>;
+    Password: React.ComponentType<PasswordProps>;
+    Email: React.ComponentType<EmailProps>;
+    Number: React.ComponentType<NumberProps>;
+    Checkbox: React.ComponentType<CheckboxProps>;
+};

package/types/ui/Loading/index.d.ts

@@ -1,8 +1,13 @@
+/**
+ * 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 declare const Loading: {
-    Area: () => import("react/jsx-runtime").JSX.Element;
-    Button: ({ className, active, style }: import("./Button.d.ts").LoadingProps) => import("react/jsx-runtime").JSX.Element;
-    Input: ({ className, active, style }: import("./Input.d.ts").LoadingProps) => import("react/jsx-runtime").JSX.Element;
-    ProgressBar: ({ className, value, max }: import("./ProgressBar.d.ts").ProgressBarProps) => import("react/jsx-runtime").JSX.Element;
-    Skeleton: ({ className, active, style }: import("./Skeleton.d.ts").SkeletonProps) => import("react/jsx-runtime").JSX.Element;
-    Spin: ({ indicator, isCenter, className }: import("./Spin.d.ts").SpinProps) => import("react/jsx-runtime").JSX.Element;
+    Area: import("react").ComponentType<Record<string, never>>;
+    Button: import("react").ComponentType<import("./Button.d.ts").LoadingProps>;
+    Input: import("react").ComponentType<import("./Input.d.ts").LoadingProps>;
+    ProgressBar: import("react").ComponentType<import("./ProgressBar.d.ts").ProgressBarProps>;
+    Skeleton: import("react").ComponentType<import("./Skeleton.d.ts").SkeletonProps>;
+    Spin: import("react").ComponentType<import("./Spin.d.ts").SpinProps>;
 };

package/types/ui/Menu.d.ts

@@ -1,12 +1,12 @@
 import { type ReactNode } from "react";
-interface MenuItem {
+export interface MenuItem {
     label: ReactNode;
     key: string;
     children?: MenuItem[];
     icon?: ReactNode;
     type?: string;
 }
-interface MenuProps {
+export interface MenuProps {
     className?: string;
     ulClassName?: string;
     liClassName?: string;
@@ -22,5 +22,10 @@ interface MenuProps {
     onMouseOver?: () => void;
     onMouseLeave?: () => void;
 }
-export declare const Menu: ({ items, onClick, selectedKeys, labelClassName, defaultSelectedKeys, className, ulClassName, liClassName, style, mode, activeStyle, inlineCollapsed, onMouseOver, onMouseLeave, }: MenuProps) => import("react/jsx-runtime").JSX.Element;
-export {};
+export declare const DefaultMenu: ({ items, onClick, selectedKeys, labelClassName, defaultSelectedKeys, className, ulClassName, liClassName, style, mode, activeStyle, inlineCollapsed, onMouseOver, onMouseLeave, }: MenuProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare const Menu: import("react").ComponentType<MenuProps>;

package/types/ui/Modal.d.ts

@@ -16,4 +16,14 @@ export interface ModalProps {
     /** Ask for close confirmation before dismissing. */
     confirmClose?: boolean;
 }
-export declare const Modal: ({ className, title, action, open, onCancel, bodyClassName, children, confirmClose, }: ModalProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Default akanjs modal skin. Kept as the fallback implementation; apps replace
+ * it per-route through a `page/**\/_overrides.tsx` manifest.
+ */
+export declare const DefaultModal: ({ className, title, action, open, onCancel, bodyClassName, children, confirmClose, }: ModalProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare const Modal: import("react").ComponentType<ModalProps>;

package/types/ui/Pagination.d.ts

@@ -17,4 +17,9 @@ export interface PaginationProps {
         pageNumClassName?: string;
     };
 }
-export declare const Pagination: FC<PaginationProps>;
+export declare const DefaultPagination: FC<PaginationProps>;
+/**
+ * Pager. Resolves to a route-scoped override when a `page/**\/_overrides.tsx` in
+ * the route's ancestry declares one, otherwise renders {@link DefaultPagination}.
+ */
+export declare const Pagination: import("react").ComponentType<PaginationProps>;

package/types/ui/Popconfirm.d.ts

@@ -24,5 +24,11 @@ export interface PopconfirmProps {
     /** Additional classes for the popover arrow/decorator. */
     decoClassName?: string;
 }
-export declare const Popconfirm: ({ title, description, onConfirm, okButtonProps, cancelButtonProps, okText, cancelText, children, triggerClassName, decoClassName, }: PopconfirmProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultPopconfirm: ({ title, description, onConfirm, okButtonProps, cancelButtonProps, okText, cancelText, children, triggerClassName, decoClassName, }: PopconfirmProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare const Popconfirm: import("react").ComponentType<PopconfirmProps>;
 export {};

package/types/ui/Radio.d.ts

@@ -6,10 +6,6 @@ export interface RadioProps {
     children: ReactNode | ReactElement | ReactElement[];
     onChange: (value: string | number | null, idx: number) => void;
 }
-export declare const Radio: {
-    ({ value, children, disabled, className, onChange }: RadioProps): import("react/jsx-runtime").JSX.Element;
-    Item: ({ value, className, children }: ItemProps) => import("react/jsx-runtime").JSX.Element;
-};
 export interface ItemProps {
     value: string | number;
     children: ReactNode | ReactElement;
@@ -17,3 +13,10 @@ export interface ItemProps {
     checked?: boolean;
     onChange?: (value: string) => void;
 }
+/**
+ * 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 declare const Radio: import("react").ComponentType<RadioProps> & {
+    Item: import("react").ComponentType<ItemProps>;
+};

package/types/ui/Select.d.ts

@@ -39,5 +39,10 @@ export interface SelectProps<T extends string | number | boolean | null | undefi
     /** Custom selected value renderer. */
     renderSelected?: (value: T) => ReactNode;
 }
-export declare const Select: <T extends string | number | boolean | null | undefined, Multiple extends boolean = false, Searchable extends boolean = false, Option extends Options<T> = Options<T>>({ label, desc, labelClassName, className, value, options, nullable, disabled, multiple, searchable, placeholder, selectClassName, selectorClassName, selectedClassName, onOpen, onChange, onSearch, renderOption, renderSelected, }: SelectProps<T, Multiple, Searchable, Option>) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare 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>) => import("react").ReactElement<SelectProps<T, Multiple, Searchable, Option>, string | import("react").JSXElementConstructor<any>>;
 export {};

package/types/ui/Table.d.ts

@@ -38,4 +38,9 @@ export interface TableProps {
     /** Custom row key resolver. */
     rowKey?: (model: any) => string;
 }
-export declare const Table: ({ columns, dataSource, loading, size, bordered, pagination, showHeader, onRow, rowClassName, rowKey, }: TableProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultTable: ({ columns, dataSource, loading, size, bordered, pagination, showHeader, onRow, rowClassName, rowKey, }: TableProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare const Table: React.ComponentType<TableProps>;

package/types/ui/ToggleSelect.d.ts

@@ -1,4 +1,5 @@
-interface ToggleSelectProps<I extends string | number | boolean | null> {
+import { type ComponentType } from "react";
+export interface ToggleSelectProps<I extends string | number | boolean | null> {
     className?: string;
     btnClassName?: string;
     items: string[] | number[] | {
@@ -12,11 +13,7 @@ interface ToggleSelectProps<I extends string | number | boolean | null> {
     onChange: (value: I, idx: number) => void;
     disabled?: boolean;
 }
-export declare const ToggleSelect: {
-    <I extends string | number | boolean | null>({ className, btnClassName, items, nullable, validate, value, onChange, disabled, }: ToggleSelectProps<I>): import("react/jsx-runtime").JSX.Element;
-    Multi: ({ className, btnClassName, items, nullable, validate, value, onChange, disabled }: MultiProps) => import("react/jsx-runtime").JSX.Element;
-};
-interface MultiProps {
+export interface MultiProps {
     className?: string;
     btnClassName?: string;
     items: string[] | number[] | {
@@ -30,4 +27,11 @@ interface MultiProps {
     onChange: (value: string[] | number[]) => void;
     disabled?: boolean;
 }
-export {};
+/**
+ * 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 declare const ToggleSelect: (<I extends string | number | boolean | null>(props: ToggleSelectProps<I>) => import("react").ReactElement<ToggleSelectProps<I>, string | import("react").JSXElementConstructor<any>>) & {
+    Multi: ComponentType<MultiProps>;
+};

package/types/ui/UiOverride/Provider.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import { type AkanUiOverrides } from "./context.d.ts";
+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 declare const UiOverrideProvider: ({ value, children }: UiOverrideProviderProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/UiOverride/context.d.ts

@@ -0,0 +1,72 @@
+import { type ComponentType } from "react";
+import type { ButtonProps } from "../Button.d.ts";
+import type { DatePickerProps, RangePickerProps, TimePickerProps } from "../DatePicker.d.ts";
+import type { DropdownProps } from "../Dropdown.d.ts";
+import type { EmptyProps } from "../Empty.d.ts";
+import type { CheckboxProps, EmailProps, InputProps, NumberProps, PasswordProps, TextAreaProps } from "../Input.d.ts";
+import type { LoadingProps as LoadingButtonProps } from "../Loading/Button.d.ts";
+import type { LoadingProps as LoadingInputProps } from "../Loading/Input.d.ts";
+import type { ProgressBarProps } from "../Loading/ProgressBar.d.ts";
+import type { SkeletonProps } from "../Loading/Skeleton.d.ts";
+import type { SpinProps } from "../Loading/Spin.d.ts";
+import type { MenuProps } from "../Menu.d.ts";
+import type { ModalProps } from "../Modal.d.ts";
+import type { PaginationProps } from "../Pagination.d.ts";
+import type { PopconfirmProps } from "../Popconfirm.d.ts";
+import type { ItemProps as RadioItemProps, RadioProps } from "../Radio.d.ts";
+import type { SelectProps } from "../Select.d.ts";
+import type { TableProps } from "../Table.d.ts";
+import type { MultiProps as ToggleSelectMultiProps, ToggleSelectProps } from "../ToggleSelect.d.ts";
+import type { UnauthorizedProps } from "../Unauthorized.d.ts";
+/**
+ * Registry of framework UI components an app may replace per-route through a
+ * `page/**\/_overrides.tsx` manifest. Each entry is keyed by the framework
+ * component name and typed to that component's public prop contract, so an
+ * override is checked as a drop-in replacement.
+ *
+ * Extend this interface (and add a matching `createOverridable(...)` call in the
+ * component file) to make another component overridable. Generic components
+ * (e.g. `Button`, `Select`) and compound components that carry static
+ * sub-components (e.g. `Tab`, `Field`, `Input`) need dedicated slot support
+ * before they can be listed here without losing call-site typing.
+ */
+export interface AkanUiOverrides {
+    Modal: ComponentType<ModalProps>;
+    Empty: ComponentType<EmptyProps>;
+    Pagination: ComponentType<PaginationProps>;
+    Popconfirm: ComponentType<PopconfirmProps>;
+    Dropdown: ComponentType<DropdownProps>;
+    Table: ComponentType<TableProps>;
+    Menu: ComponentType<MenuProps>;
+    Unauthorized: ComponentType<UnauthorizedProps>;
+    Button: ComponentType<ButtonProps<unknown>>;
+    Select: ComponentType<SelectProps<string | number | boolean | null | undefined>>;
+    Input: ComponentType<InputProps>;
+    InputTextArea: ComponentType<TextAreaProps>;
+    InputPassword: ComponentType<PasswordProps>;
+    InputEmail: ComponentType<EmailProps>;
+    InputNumber: ComponentType<NumberProps>;
+    InputCheckbox: ComponentType<CheckboxProps>;
+    Radio: ComponentType<RadioProps>;
+    RadioItem: ComponentType<RadioItemProps>;
+    DatePicker: ComponentType<DatePickerProps>;
+    DatePickerRangePicker: ComponentType<RangePickerProps>;
+    DatePickerTimePicker: ComponentType<TimePickerProps>;
+    ToggleSelect: ComponentType<ToggleSelectProps<string | number | boolean | null>>;
+    ToggleSelectMulti: ComponentType<ToggleSelectMultiProps>;
+    LoadingSpin: ComponentType<SpinProps>;
+    LoadingSkeleton: ComponentType<SkeletonProps>;
+    LoadingProgressBar: ComponentType<ProgressBarProps>;
+    LoadingButton: ComponentType<LoadingButtonProps>;
+    LoadingInput: ComponentType<LoadingInputProps>;
+    LoadingArea: ComponentType<Record<string, never>>;
+}
+export type AkanUiOverrideName = keyof AkanUiOverrides;
+/** Prop contract an app-authored Modal override must satisfy. */
+export type AkanModalComponent = AkanUiOverrides["Modal"];
+/**
+ * Holds the override map for the current route subtree. Empty at the root, then
+ * merged (child wins) by each nested `UiOverrideProvider`, mirroring how nested
+ * `_layout.tsx` / `_overrides.tsx` stack down the route tree.
+ */
+export declare const UiOverrideContext: import("react").Context<Partial<AkanUiOverrides>>;

package/types/ui/UiOverride/createOverridable.d.ts

@@ -0,0 +1,9 @@
+import type { AkanUiOverrides } from "./context.d.ts";
+/**
+ * Wraps a framework component so a matching `_overrides.tsx` entry replaces it,
+ * scoped to that route subtree. Falls back to `Default` when no override is
+ * active, so every existing call site keeps working untouched. The proxy erases
+ * its prop type internally and re-asserts the slot's public component type on
+ * the way out, so call sites stay fully typed against the slot contract.
+ */
+export declare const createOverridable: <K extends keyof AkanUiOverrides>(name: K, Default: AkanUiOverrides[K]) => AkanUiOverrides[K];

package/types/ui/UiOverride/index.d.ts

@@ -0,0 +1,5 @@
+export type { AkanModalComponent, AkanUiOverrideName, AkanUiOverrides } from "./context.d.ts";
+export { createOverridable } from "./createOverridable.d.ts";
+export { override } from "./override.d.ts";
+export { UiOverrideProvider, type UiOverrideProviderProps } from "./Provider.d.ts";
+export { useUiOverride } from "./useUiOverride.d.ts";

package/types/ui/UiOverride/override.d.ts

@@ -0,0 +1,18 @@
+import type { AkanUiOverrides } from "./context.d.ts";
+/**
+ * Typed manifest builder for a `page/_overrides.tsx` file:
+ *
+ * ```tsx
+ * export default override({ Modal: BrandModal });
+ * ```
+ *
+ * It type-checks each binding against that slot's public component contract and rejects unknown slot names as
+ * excess properties — so the manifest is validated at compile time and app components need no annotation of
+ * their own. Keys are the framework component names (`Modal`), matching `useUiOverride` and the `<Modal>` call
+ * sites.
+ *
+ * It is a pure, server-safe identity function (no React, no `createContext`), so the manifest needs no
+ * `"use client"` directive. The framework generates a `"use client"` wrapper layout that reads this map and
+ * mounts the override provider around the route subtree (see `writeGeneratedOverridesLayoutFile`).
+ */
+export declare const override: (overrides: Partial<AkanUiOverrides>) => Partial<AkanUiOverrides>;

package/types/ui/UiOverride/useUiOverride.d.ts

@@ -0,0 +1,7 @@
+import { type AkanUiOverrides } from "./context.d.ts";
+/**
+ * Resolves the active override for a framework component in the current route
+ * subtree, or `undefined` when no `_overrides.tsx` in the route's ancestry
+ * declares one.
+ */
+export declare const useUiOverride: <K extends keyof AkanUiOverrides>(name: K) => AkanUiOverrides[K] | undefined;

package/types/ui/UiOverride.d.ts

@@ -0,0 +1 @@
+export * from "./UiOverride/index.d.ts";