akanjs 2.3.11-rc.8 → 2.3.11

package/ui/UiOverride/context.ts

@@ -0,0 +1,85 @@
+"use client";
+import { type ComponentType, createContext } from "react";
+
+import type { ButtonProps } from "../Button";
+import type { DatePickerProps, RangePickerProps, TimePickerProps } from "../DatePicker";
+import type { DropdownProps } from "../Dropdown";
+import type { EmptyProps } from "../Empty";
+import type { CheckboxProps, EmailProps, InputProps, NumberProps, PasswordProps, TextAreaProps } from "../Input";
+import type { LoadingProps as LoadingButtonProps } from "../Loading/Button";
+import type { LoadingProps as LoadingInputProps } from "../Loading/Input";
+import type { ProgressBarProps } from "../Loading/ProgressBar";
+import type { SkeletonProps } from "../Loading/Skeleton";
+import type { SpinProps } from "../Loading/Spin";
+import type { MenuProps } from "../Menu";
+import type { ModalProps } from "../Modal";
+import type { PaginationProps } from "../Pagination";
+import type { PopconfirmProps } from "../Popconfirm";
+import type { ItemProps as RadioItemProps, RadioProps } from "../Radio";
+import type { SelectProps } from "../Select";
+import type { TableProps } from "../Table";
+import type { MultiProps as ToggleSelectMultiProps, ToggleSelectProps } from "../ToggleSelect";
+import type { UnauthorizedProps } from "../Unauthorized";
+
+/**
+ * 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 const UiOverrideContext = createContext<Partial<AkanUiOverrides>>({});

package/ui/UiOverride/createOverridable.tsx

@@ -0,0 +1,25 @@
+"use client";
+import { type ComponentType, createElement, type ReactNode } from "react";
+
+import type { AkanUiOverrides } from "./context";
+import { useUiOverride } from "./useUiOverride";
+
+/**
+ * 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 const createOverridable = <K extends keyof AkanUiOverrides>(
+  name: K,
+  Default: AkanUiOverrides[K],
+): AkanUiOverrides[K] => {
+
+  const Fallback = Default as unknown as ComponentType<Record<string, unknown>>;
+  const Overridable = (props: Record<string, unknown>): ReactNode => {
+    const Override = useUiOverride(name) as unknown as ComponentType<Record<string, unknown>> | undefined;
+    return createElement(Override ?? Fallback, props);
+  };
+  return Overridable as unknown as AkanUiOverrides[K];
+};

package/ui/UiOverride/index.ts

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

package/ui/UiOverride/override.ts

@@ -0,0 +1,19 @@
+import type { AkanUiOverrides } from "./context";
+
+/**
+ * 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 const override = (overrides: Partial<AkanUiOverrides>): Partial<AkanUiOverrides> => overrides;

package/ui/UiOverride/useUiOverride.ts

@@ -0,0 +1,15 @@
+"use client";
+import { useContext } from "react";
+
+import { type AkanUiOverrides, UiOverrideContext } from "./context";
+
+/**
+ * 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 const useUiOverride = <K extends keyof AkanUiOverrides>(name: K): AkanUiOverrides[K] | undefined => {
+
+  const overrides = useContext(UiOverrideContext) as Record<string, unknown>;
+  return overrides[name] as AkanUiOverrides[K] | undefined;
+};

package/ui/Unauthorized.tsx

@@ -1,16 +1,18 @@
-
+"use client";
 import { clsx, usePage } from "akanjs/client";
 import type { ReactNode } from "react";
 import { AiOutlineBlock } from "react-icons/ai";
 
-interface UnauthorizedProps {
+import { createOverridable } from "./UiOverride";
+
+export interface UnauthorizedProps {
   className?: string;
   description?: ReactNode;
   children?: ReactNode;
   minHeight?: number;
 }
 
-export const Unauthorized = ({ className = "", description, children, minHeight = 300 }: UnauthorizedProps) => {
+export const DefaultUnauthorized = ({ className = "", description, children, minHeight = 300 }: UnauthorizedProps) => {
   const { l } = usePage();
   return (
     <div>
@@ -27,3 +29,10 @@ export const Unauthorized = ({ className = "", description, children, minHeight
     </div>
   );
 };
+
+/**
+ * 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 const Unauthorized = createOverridable("Unauthorized", DefaultUnauthorized);

package/ui/index.ts

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

package/webkit/bootCsr.tsx

@@ -7,12 +7,12 @@ import {
   type LayoutModule,
   type PageConfig,
   type PathRoute,
-  readCssSafeAreaInsets,
-  resolvePageState,
   type Route,
   type RouteGuide,
   type RouteModule,
   type RouteRender,
+  readCssSafeAreaInsets,
+  resolvePageState,
   storage,
   validatePageConfig,
 } from "akanjs/client";
@@ -113,7 +113,8 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
       validateRouteModuleExports(key, pageContent);
       validatePageConfig(key, (pageContent as RouteModuleWithConfig).pageConfig);
       asyncDefaultMap[key] = entry.isAsyncDefault;
-      if (pageContent.default) pages[key] = pageContent;
+      
+      if (pageContent.default || parsed.kind === "overrides") pages[key] = pageContent;
     }),
   );
   const cssSafeArea = readCssSafeAreaInsets();
@@ -138,6 +139,18 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
     if (!targetPath) continue;
     const page = pages[filePath];
     if (!page) continue;
+    if (parsed.kind === "overrides") {
+      
+      const overridesRender: RouteRender = {
+        render: page.default as never,
+        isAsync: asyncDefaultMap[filePath] || page.default?.constructor.name === "AsyncFunction",
+      };
+      targetRouteMap.set(targetPath, {
+        ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
+        renderOverrides: overridesRender,
+      } as Route);
+      continue;
+    }
     const layoutPage = parsed.kind === "layout" ? (page as LayoutModule) : null;
     const routeRender: RouteRender = {
       render: page.default as never,
@@ -179,15 +192,20 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
     const currentRootLayout = isRoot && route.renderLayout ? route.renderLayout : null;
     const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
     const currentLayoutConfig = route.renderLayout && route.layoutPageConfig ? route.layoutPageConfig : null;
+
+    const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
     const renderRootLayouts = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
+    const renderLayouts = [...parentLayouts, ...currentOverrideRenders, ...(currentLayout ? [currentLayout] : [])];
     const pageConfigChain = [
       ...parentPageConfigChain,
       ...(currentRootLayout || currentLayout ? (currentLayoutConfig ? [currentLayoutConfig] : []) : []),
     ];
     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 pageRenderConfigChain =
       route.pageIncludesOwnLayout === false && (currentRootLayout || currentLayout)
         ? parentPageConfigChain
@@ -280,6 +298,11 @@ function initializeMobileTargetFromSearch() {
 
 function validateRouteModuleExports(key: string, mod: RouteModule) {
   const parsed = parseRouteModuleKey(key);
+  if (parsed.kind === "overrides") {
+    
+    if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
+    return;
+  }
   const allowed =
     parsed.kind === "page"
       ? new Set(["default", "pageConfig", "head", "metadata", "generateHead", "generateMetadata", "Loading"])