akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/ui/Portal.tsx

@@ -10,9 +10,8 @@ interface PortalProps {
 }
 
 export const Portal = ({ children, id }: PortalProps) => {
-  const [targetElement, setTargetElement] = useState<HTMLElement | null>(() =>
-    typeof document === "undefined" ? null : document.getElementById(id),
-  );
+
+  const [targetElement, setTargetElement] = useState<HTMLElement | null>(null);
 
   useLayoutEffect(() => {
     setTargetElement(document.getElementById(id));

package/ui/Radio.tsx

@@ -15,7 +15,7 @@ export interface RadioProps {
 const DefaultRadio = ({ value, children, disabled, className, onChange }: RadioProps) => {
   const ref = useRef<HTMLDivElement>(null);
   const items = Children.toArray(children) as ReactElement<{ value: string | number | null }>[];
-
+  
   const byValue = items.findIndex((child) => child.props?.value === value);
   const checkedIdx = byValue >= 0 ? byValue : typeof value === "number" ? value : -1;
 
@@ -84,10 +84,6 @@ const DefaultItem = ({ className, children }: ItemProps) => (
 
 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/RecentTime.tsx

@@ -21,19 +21,15 @@ export interface RecentTimeRelative {
 export type RecentTimeRelativeFormat = RecentTimeRelativeStyle | ((relative: RecentTimeRelative) => string);
 
 export interface RecentTimeProps {
-  /** Date value to render. Null renders nothing, and epoch placeholder values render --:--. */
+  /** Null renders nothing; an epoch placeholder renders --:--. */
   date: Date | Dayjs | null;
-  /** Unit at which relative labels stop and formatted dates are shown instead. */
+  /** The unit past which a formatted date replaces the relative label. */
   breakUnit?: Intl.RelativeTimeFormatUnit;
-  /** Use compact automatic formatting or always include date and time. */
+  /** `"full"` always includes date and time. */
   format?: "full" | "auto";
-  /**
-   * Relative phrasing. `"fromNow"` (default) keeps dayjs locale strings (`하루 전`).
-   * `"always"` / `"auto"` use `Intl.RelativeTimeFormat` — `1일 전` vs `어제`.
-   * A function replaces the relative label; return `defaultLabel` to keep the default.
-   */
+  /** `"fromNow"` (default) keeps dayjs locale strings (`하루 전`); `"always"` / `"auto"` use `Intl.RelativeTimeFormat`
+   *  (`1일 전` vs `어제`); a function replaces the label, returning `defaultLabel` to keep it. */
   relative?: RecentTimeRelativeFormat;
-  /** Additional classes for the trigger span. */
   className?: string;
 }
 
@@ -65,29 +61,21 @@ const formatRelativeLabel = (date: Dayjs, now: Dayjs, lang: string, relative: Re
   return new Intl.RelativeTimeFormat(lang, { numeric: relative }).format(count, unit);
 };
 
+const relativeLimits = [
+  ["second", 1000, 60],
+  ["minute", 1000 * 60, 60],
+  ["hour", 1000 * 3600, 24],
+  ["day", 1000 * 3600 * 24, 7],
+  ["week", 1000 * 3600 * 24 * 7, 4],
+  ["month", 1000 * 3600 * 24 * 30, 12],
+] as const;
+
 const isRelativeDisplay = (diffMs: number, breakUnit?: Intl.RelativeTimeFormatUnit) => {
-  const elapsed = {
-    second: Math.abs(Math.floor(diffMs / 1000)),
-    minute: Math.abs(Math.floor(diffMs / (1000 * 60))),
-    hour: Math.abs(Math.floor(diffMs / (1000 * 3600))),
-    day: Math.abs(Math.floor(diffMs / (1000 * 3600 * 24))),
-    week: Math.abs(Math.floor(diffMs / (1000 * 3600 * 24 * 7))),
-    month: Math.abs(Math.floor(diffMs / (1000 * 3600 * 24 * 30))),
-  };
-  if (breakUnit === "second") return false;
-  if (elapsed.second < 60) return true;
-  if (breakUnit === "minute") return false;
-  if (elapsed.minute < 60) return true;
-  if (breakUnit === "hour") return false;
-  if (elapsed.hour < 24) return true;
-  if (breakUnit === "day") return false;
-  if (elapsed.day < 7) return true;
-  if (breakUnit === "week") return false;
-  if (elapsed.week < 4) return true;
-  if (breakUnit === "month") return false;
-  if (elapsed.month < 12) return true;
-  if (breakUnit === "year") return false;
-  return true;
+  for (const [unit, unitMs, limit] of relativeLimits) {
+    if (breakUnit === unit) return false;
+    if (Math.abs(Math.floor(diffMs / unitMs)) < limit) return true;
+  }
+  return breakUnit !== "year";
 };
 
 export const RecentTime = ({ date, breakUnit, format = "auto", relative = "fromNow", className }: RecentTimeProps) => {

package/ui/Reference/Panel.tsx

@@ -1,9 +1,10 @@
 import { cn } from "akanjs/client";
 import type { ReactNode, RefObject } from "react";
 import { AiOutlineCopy } from "react-icons/ai";
+import { BiChevronDown } from "react-icons/bi";
 import { buttonRecipe } from "../Button";
 import { Copy } from "../Copy";
-import { docBorder, docDash, docUi } from "./style";
+import { docBorder, docDash, docUi } from "./docUi";
 
 interface PanelProps {
   className?: string;
@@ -11,7 +12,6 @@ interface PanelProps {
   label?: string;
   meta?: ReactNode;
   tone?: Parameters<typeof docBorder>[0];
-  /** Rendered outside the scrolling body so it can cover the whole panel. */
   overlay?: ReactNode;
   children: ReactNode;
 }
@@ -36,6 +36,23 @@ export const Panel = ({ className, bodyClassName, label, meta, tone = "muted", o
   </div>
 );
 
+interface DocTableProps {
+  className?: string;
+  head: ReactNode;
+  children: ReactNode;
+}
+
+export const DocTable = ({ className, head, children }: DocTableProps) => (
+  <div className={cn(docUi.tablePanel, className)}>
+    <table className={docUi.tableClass}>
+      <thead>
+        <tr>{head}</tr>
+      </thead>
+      <tbody>{children}</tbody>
+    </table>
+  </div>
+);
+
 interface CodeProps {
   className?: string;
   label?: string;
@@ -47,10 +64,6 @@ interface CodeProps {
   overlay?: ReactNode;
 }
 
-/**
- * Read-only code surface. A `<pre>` rather than a `<textarea>`: every one of these panels ignored what was typed
- * into it, so the caret and the resize grip were promising an edit that never landed anywhere.
- */
 export const Code = ({ className, label, code, tone, meta, placeholder = "—", bodyRef, overlay }: CodeProps) => (
   <Panel
     bodyClassName="max-h-none overflow-visible p-0"
@@ -77,3 +90,86 @@ export const Code = ({ className, label, code, tone, meta, placeholder = "—",
     </pre>
   </Panel>
 );
+
+interface CollapseProps {
+  className?: string;
+  contentClassName?: string;
+  summary: ReactNode;
+  children: ReactNode;
+  open?: boolean;
+}
+
+export const Collapse = ({ summary, children, open, className, contentClassName }: CollapseProps) => (
+  <details
+    className={cn(docUi.card, "group overflow-hidden transition-colors hover:border-foreground/20", className)}
+    open={open}
+  >
+    <summary className="flex cursor-pointer list-none items-start gap-3 px-4 py-3 transition-colors hover:bg-muted/40 [&::-webkit-details-marker]:hidden">
+      <div className="min-w-0 flex-1">{summary}</div>
+      <BiChevronDown className="mt-1 shrink-0 text-foreground/30 transition-transform group-open:rotate-180" />
+    </summary>
+    <div className={cn("flex w-full flex-col gap-4 border-border/70 border-t p-4", contentClassName)}>{children}</div>
+  </details>
+);
+
+interface SummaryCardProps {
+  className?: string;
+  label: string;
+  value: number | string;
+}
+
+export const SummaryCard = ({ className, label, value }: SummaryCardProps) => (
+  <div className={cn(docUi.card, "px-4 py-3", className)}>
+    <div className={docUi.sectionLabel}>{label}</div>
+    <div className="font-bold text-2xl">{value}</div>
+  </div>
+);
+
+interface SummaryGridProps {
+  className?: string;
+  children: ReactNode;
+}
+
+export const SummaryGrid = ({ className, children }: SummaryGridProps) => (
+  <div className={cn("grid grid-cols-2 gap-2 md:grid-cols-4", className)}>{children}</div>
+);
+
+interface ToolbarProps {
+  className?: string;
+  children: ReactNode;
+}
+
+export const Toolbar = ({ className, children }: ToolbarProps) => (
+  <div className={cn(docUi.card, "flex flex-wrap items-center gap-x-6 gap-y-3 px-4 py-3", className)}>{children}</div>
+);
+
+interface ToolbarFieldProps {
+  className?: string;
+  label: string;
+  children: ReactNode;
+}
+
+export const ToolbarField = ({ className, label, children }: ToolbarFieldProps) => (
+  <div className={cn("flex min-w-0 items-center gap-2", className)}>
+    <span className={docUi.sectionLabel}>{label}</span>
+    {children}
+  </div>
+);
+
+interface SectionProps {
+  className?: string;
+  title: string;
+  action?: ReactNode;
+  children: ReactNode;
+}
+
+export const Section = ({ className, title, action, children }: SectionProps) => (
+  <section className={cn("flex flex-col gap-3", className)}>
+    <div className="flex items-center gap-3">
+      <h2 className={docUi.sectionTitle}>{title}</h2>
+      <div className="h-px flex-1 bg-border" />
+      {action}
+    </div>
+    {children}
+  </section>
+);

package/ui/Reference/Segmented.tsx

@@ -15,20 +15,14 @@ interface SegmentedProps<Key extends string> {
   onChange: (value: Key) => void;
 }
 
-/** The track and its items are also the shape of a multi-select chip group, which `Segmented` itself cannot be. */
-export const segmentTrackClass = "inline-flex w-fit flex-wrap gap-1 rounded-field bg-muted p-1";
-
-export const segmentItemClass = (active: boolean) =>
-  cn(
-    "inline-flex items-center gap-1.5 rounded-[calc(var(--radius-field)-0.25rem)] px-3 py-1.5 font-medium text-sm transition-colors",
-    active ? "bg-background text-foreground shadow-sm" : "text-foreground/50 hover:text-foreground",
-  );
-
 export const Segmented = <Key extends string>({ className, items, value, onChange }: SegmentedProps<Key>) => (
-  <div className={cn(segmentTrackClass, className)}>
+  <div className={cn("inline-flex w-fit flex-wrap gap-1 rounded-field bg-muted p-1", className)}>
     {items.map((item) => (
       <button
-        className={segmentItemClass(item.key === value)}
+        className={cn(
+          "inline-flex items-center gap-1.5 rounded-[calc(var(--radius-field)-0.25rem)] px-3 py-1.5 font-medium text-sm transition-colors",
+          item.key === value ? "bg-background text-foreground shadow-sm" : "text-foreground/50 hover:text-foreground",
+        )}
         key={item.key}
         onClick={() => onChange(item.key)}
         type="button"

package/ui/Reference/docUi.ts

@@ -0,0 +1,53 @@
+import { cn } from "../../client/cn";
+
+export type Tone = "info" | "success" | "warning" | "error" | "muted";
+
+const toneFill: { [key in Tone]: string } = {
+  info: "bg-info/15 text-info ring-info/25",
+  success: "bg-success/15 text-success ring-success/25",
+  warning: "bg-warning/15 text-warning ring-warning/25",
+  error: "bg-destructive/15 text-destructive ring-destructive/25",
+  muted: "bg-muted text-foreground/60 ring-border",
+};
+
+const toneBorder: { [key in Tone]: string } = {
+  info: "border-info/40",
+  success: "border-success/40",
+  warning: "border-warning/40",
+  error: "border-destructive/40",
+  muted: "border-border",
+};
+
+const pill = "inline-flex items-center gap-1 rounded-full px-2 py-0.5 font-medium text-xs ring-1 ring-inset";
+
+export const docUi = {
+  card: "rounded-box border border-border bg-card",
+  panel: "rounded-box border border-border bg-background",
+  tablePanel: "overflow-x-auto rounded-box border border-border bg-background",
+  sectionLabel: "font-semibold text-foreground/45 text-xs uppercase tracking-wider",
+  sectionTitle: "font-bold text-xl",
+  pageTitle: "font-bold text-3xl",
+  sectionDescription: "text-foreground/70 text-sm",
+  prose: "text-foreground/75 text-sm leading-relaxed",
+  key: "font-medium font-mono",
+  subLabel: "text-foreground/45 text-xs",
+  tableClass:
+    "w-full text-left text-sm [&_th]:whitespace-nowrap [&_th]:px-3 [&_th]:py-2 [&_th]:font-semibold [&_th]:text-foreground/45 [&_th]:text-xs [&_th]:uppercase [&_th]:tracking-wider [&_td]:px-3 [&_td]:py-2.5 [&_td]:align-top [&_tbody_tr]:border-border/70 [&_tbody_tr]:border-t [&_tbody_tr]:transition-colors hover:[&_tbody_tr]:bg-muted/40",
+  emptyPanel: "rounded-box border border-border border-dashed p-8 text-center text-foreground/40 text-sm",
+};
+
+export const docPill = (tone: Tone, className?: string) => cn(pill, toneFill[tone], className);
+
+export const docBorder = (tone: Tone) => toneBorder[tone];
+
+export const docDash = "text-foreground/25";
+
+interface Translator {
+  _: (key: string) => string;
+}
+
+/** `l._` echoes an absent key back, and a raw `user.signal.x.desc` reads as prose on a document surface. */
+export const dictText = (l: Translator, key: string) => {
+  const text = l._(key);
+  return text === key ? "" : text;
+};

package/ui/Reference/index.ts

@@ -1,7 +1,3 @@
-export { Collapse } from "./Collapse";
-export { dictText } from "./dictText";
-export { Code, Panel } from "./Panel";
-export { Segmented, type SegmentedItem, segmentItemClass, segmentTrackClass } from "./Segmented";
-export { SummaryCard, SummaryGrid } from "./Summary";
-export { docDash, docPill, docUi, type Tone } from "./style";
-export { Section, Toolbar, ToolbarField } from "./Toolbar";
+export { dictText, docDash, docPill, docUi, type Tone } from "./docUi";
+export { Code, Collapse, DocTable, Panel, Section, SummaryCard, SummaryGrid, Toolbar, ToolbarField } from "./Panel";
+export { Segmented, type SegmentedItem } from "./Segmented";

package/ui/Refresh.tsx

@@ -1,11 +1,19 @@
 "use client";
-import { lazy } from "akanjs/webkit";
-import type { ReactElement } from "react";
+import { type ReactElement, useEffect, useRef, useState } from "react";
 import { BiLoaderAlt } from "react-icons/bi";
 
-const pullToRefreshPackage = "react-simple-pull-to-refresh";
+const pullDownThreshold = 67;
+const maxPullDownDistance = 95;
 
-const PullToRefresh = lazy(() => import(pullToRefreshPackage), { ssr: false });
+const isScrolledDown = (element: Element | null) => {
+  for (let node = element; node; node = node.parentElement) {
+    const { overflowY } = getComputedStyle(node);
+    const scrollable =
+      overflowY === "auto" || overflowY === "scroll" || (node === document.scrollingElement && overflowY === "visible");
+    if (scrollable && node.scrollTop > 0) return true;
+  }
+  return false;
+};
 
 interface RefreshProps {
   children: ReactElement;
@@ -13,16 +21,74 @@ interface RefreshProps {
 }
 
 export const Refresh = ({ children, onRefresh }: RefreshProps) => {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const onRefreshRef = useRef(onRefresh);
+  onRefreshRef.current = onRefresh;
+  const [pull, setPull] = useState(0);
+  const [refreshing, setRefreshing] = useState(false);
+
+  useEffect(() => {
+    const content = contentRef.current;
+    if (!content) return;
+    let startY: number | null = null;
+    let distance = 0;
+    const onStart = (event: TouchEvent) => {
+      const blocked = isScrolledDown(event.target as Element) || content.getBoundingClientRect().top < 0;
+      startY = blocked ? null : (event.touches[0]?.pageY ?? null);
+      distance = 0;
+    };
+    const onMove = (event: TouchEvent) => {
+      if (startY === null) return;
+      const y = event.touches[0]?.pageY ?? startY;
+      if (y < startY) {
+        startY = null;
+        setPull(0);
+        return;
+      }
+      if (event.cancelable) event.preventDefault();
+      distance = Math.min(y - startY, maxPullDownDistance);
+      setPull(distance);
+    };
+    const onEnd = () => {
+      const breached = startY !== null && distance >= pullDownThreshold;
+      startY = null;
+      distance = 0;
+      setPull(0);
+      if (!breached) return;
+      setRefreshing(true);
+      void onRefreshRef.current().finally(() => setRefreshing(false));
+    };
+    
+    content.addEventListener("touchstart", onStart, { passive: true });
+    content.addEventListener("touchmove", onMove, { passive: false });
+    content.addEventListener("touchend", onEnd);
+    content.addEventListener("touchcancel", onEnd);
+    return () => {
+      content.removeEventListener("touchstart", onStart);
+      content.removeEventListener("touchmove", onMove);
+      content.removeEventListener("touchend", onEnd);
+      content.removeEventListener("touchcancel", onEnd);
+    };
+  }, []);
+
+  const offset = refreshing ? pullDownThreshold : pull;
   return (
-    <PullToRefresh
-      onRefresh={onRefresh}
-      refreshingContent={
-        <div className="fixed left-1/2 flex size-10 -translate-x-1/2 items-center justify-center rounded-full bg-background shadow-sm">
-          <BiLoaderAlt className="animate-spin text-2xl" />
+    <div className="relative size-full overflow-hidden">
+      {offset > 0 ? (
+        <div
+          className="fixed left-1/2 flex size-10 -translate-x-1/2 items-center justify-center rounded-full bg-background shadow-sm"
+          style={{ opacity: refreshing ? 1 : Math.min(pull / pullDownThreshold, 1) }}
+        >
+          <BiLoaderAlt className={refreshing ? "animate-spin text-2xl" : "text-2xl"} />
         </div>
-      }
-    >
-      {children}
-    </PullToRefresh>
+      ) : null}
+      <div
+        ref={contentRef}
+        className="size-full overflow-y-auto overflow-x-hidden transition-transform duration-200 ease-out"
+        style={offset ? { transform: `translateY(${offset}px)` } : undefined}
+      >
+        {children}
+      </div>
+    </div>
   );
 };

package/ui/ScreenNavigator.tsx

@@ -27,21 +27,14 @@ const ScreenNavigatorContext = sharedContext<ScreenNavigatorContextType>("screen
 });
 
 interface ScreenNavigatorProps {
-  
   children: React.ReactNode;
   setMenu?: (menu: string) => void;
   menus: string[];
-  /** Names this navigator for the in-page agent. Without it it publishes nothing — two on one screen would share a name. */
+  /** Names this navigator for the in-page agent; without it it publishes nothing. */
   namespace?: string;
 }
 
-export const ScreenNavigator = ({
-  children,
-  setMenu = () => {
-  },
-  menus,
-  namespace,
-}: ScreenNavigatorProps) => {
+export const ScreenNavigator = ({ children, setMenu = () => {}, menus, namespace }: ScreenNavigatorProps) => {
   const [currentMenu, setCurrentMenu] = useState(menus[0]);
   const xValue = useSpringValue(0, { config: { clamp: true } });
   const ref = useRef<HTMLDivElement>(null);
@@ -112,9 +105,11 @@ export const ScreenNavigator = ({
 
   return (
     <ScreenNavigatorContext.Provider value={{ bind, xValue, onClickMenu, menus, currentMenu, setMenu }}>
-      <animated.div {...bind()} className="flex h-full w-[200vw] overflow-x-scroll" style={{ x: xValue }} ref={ref}>
-        {children}
-      </animated.div>
+      <div className="h-full w-full overflow-hidden">
+        <animated.div {...bind()} className="flex h-full w-[200%]" style={{ x: xValue }} ref={ref}>
+          {children}
+        </animated.div>
+      </div>
     </ScreenNavigatorContext.Provider>
   );
 };
@@ -136,7 +131,7 @@ ScreenNavigator.NavbarItem = NavbarItem;
 
 const Screen = ({ children }: { children: React.ReactNode }) => {
   return (
-    <div className="h-full w-screen overflow-scroll" style={{ touchAction: "pan-y" }}>
+    <div className="h-full w-1/2 overflow-scroll" style={{ touchAction: "pan-y" }}>
       {children}
     </div>
   );

package/ui/Select.tsx

@@ -21,9 +21,12 @@ import { BsQuestionCircleFill } from "react-icons/bs";
 import { TiDelete } from "react-icons/ti";
 import { agentAttrs } from "./agentAttrs";
 import { Label } from "./Field/Label";
+import { Spin } from "./Loading/Spin";
 import { overlayZ, useOverlayLayerProps } from "./overlayLayer";
 import { useOverlayPosition } from "./overlayPosition";
-import { useUiOverride } from "./UiOverride";
+import { createOverridable, useUiOverride } from "./UiOverride";
+
+const LoadingSpin = createOverridable("LoadingSpin", Spin);
 
 interface LabelOption<T> {
   label: string | boolean | number;
@@ -37,39 +40,29 @@ export interface SelectProps<
   Searchable extends boolean = false,
   Option extends Options<T> = Options<T>,
 > {
-  /** Optional label shown above the selector. */
   label?: ReactNode;
-  /** Optional tooltip/help description next to the label. */
   desc?: ReactNode;
   labelClassName?: string;
   className?: string;
-  /** Controlled selected value, or selected values when multiple is true. */
   value: Multiple extends true ? T[] : T;
-  /** Option values, label/value pairs, or an Akan enum instance. */
   options: Searchable extends true ? (T extends string ? Option : LabelOption<T>[]) : Option;
-  /** Enable selecting multiple values. */
   multiple?: Multiple;
-  /** Enable search input inside the selector. */
   searchable?: Searchable;
   placeholder?: string;
   selectClassName?: string;
   selectorClassName?: string;
   selectedClassName?: string;
-  /** Allow no value to be selected: offers a clear row and the clear button. */
+  /** Offers a clear row and a clear button. */
   nullable?: boolean;
-  /** Disable open and selection behavior. */
   disabled?: boolean;
-  /** Called when the dropdown opens. */
+  /** Shows a spinner in place of the empty placeholder. */
+  loading?: boolean;
   onOpen?: () => void;
-  /** Controlled change callback. Receives next and previous value. */
   onChange: Multiple extends true ? (value: T[], prev: T[]) => void : (value: T, prev: T) => void;
-  /** Optional remote/local search callback. */
+  /** Replaces local filtering; debounced 300ms and never called with empty text. */
   onSearch?: (text: string) => void;
-  /** Placeholder for a selector with no options to offer. */
   empty?: ReactNode;
-  /** Custom option renderer. */
   renderOption?: (value: T) => ReactNode;
-  /** Custom selected value renderer. */
   renderSelected?: (value: T) => ReactNode;
 }
 
@@ -87,6 +80,7 @@ const DefaultSelect = <
   options,
   nullable,
   disabled,
+  loading,
   multiple,
   searchable,
   placeholder,
@@ -119,16 +113,15 @@ const DefaultSelect = <
   }, [options]);
 
   const [searchText, setSearchText] = useState("");
-
+  
   const [portal, setPortal] = useState<HTMLElement | null>(null);
   const [searchOptions, setSearchOptions] = useState<LabelOption<T>[]>(labeledOptions);
   const [activeIdx, setActiveIdx] = useState(-1);
   const listId = useId();
   const dropdownRef = useRef<HTMLDivElement>(null);
-
+  
   const fieldRef = useRef<HTMLDivElement>(null);
   const optionsRef = useRef<HTMLDivElement>(null);
-  
   const overlayLayerProps = useOverlayLayerProps();
   const position = useOverlayPosition({
     opened: isOpen,
@@ -286,20 +279,20 @@ const DefaultSelect = <
         <span className="flex w-full flex-wrap items-center gap-1">
           {multiple
             ? selectedValues.map((v, index) => {
+                
                 const optionValue = labeledOptions.find((option) => option.value === v);
-                if (!optionValue) return null;
                 return (
                   <div
                     key={index}
                     className="flex items-center gap-2 rounded-field bg-primary px-2 py-1 text-primary-foreground text-xs"
                   >
-                    {renderSelected ? renderSelected(optionValue.value) : optionValue.label}
+                    {renderSelected ? renderSelected(v) : (optionValue?.label ?? String(v))}
                     <button
                       type="button"
                       onClick={(e) => {
                         e.stopPropagation();
                         e.preventDefault();
-                        onSelect(optionValue.value);
+                        onSelect(v);
                       }}
                       className="opacity-50 duration-300 hover:opacity-100"
                     >
@@ -314,8 +307,8 @@ const DefaultSelect = <
               {(() => {
                 
                 const optionValue = labeledOptions.find((option) => selected(option.value));
-                if (!optionValue) return null;
-                return renderSelected ? renderSelected(optionValue.value) : optionValue.label;
+                const v = selectedValues[0] as T;
+                return renderSelected ? renderSelected(v) : (optionValue?.label ?? String(v));
               })()}
             </div>
           ) : null}
@@ -373,7 +366,7 @@ const DefaultSelect = <
               aria-hidden={!isOpen}
               {...overlayLayerProps}
               data-open={isOpen}
-
+              
               style={{
                 position: "fixed",
                 zIndex: overlayZ.select,
@@ -431,14 +424,18 @@ const DefaultSelect = <
                   </div>
                 );
               })}
-              {searchOptions.length
-                ? null
-                : (empty ?? (
-                    <div className="flex size-full flex-col items-center justify-center gap-2 p-2 text-center text-5xl text-foreground/50">
-                      <BsQuestionCircleFill />
-                      <div className="text-sm">{l("base.noOptions")}</div>
-                    </div>
-                  ))}
+              {searchOptions.length ? null : loading ? (
+                <div className="flex size-full items-center justify-center p-4">
+                  <LoadingSpin />
+                </div>
+              ) : (
+                (empty ?? (
+                  <div className="flex size-full flex-col items-center justify-center gap-2 p-2 text-center text-5xl text-foreground/50">
+                    <BsQuestionCircleFill />
+                    <div className="text-sm">{l("base.noOptions")}</div>
+                  </div>
+                ))
+              )}
             </div>,
             portal,
           )
@@ -447,11 +444,6 @@ const DefaultSelect = <
   );
 };
 
-/**
- * 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,