akanjs 3.0.0-alpha.60 → 3.0.0-alpha.61

package/constant/labelOf.ts

@@ -1,11 +1,20 @@
 /**
- * The one line a human scans for, derived from what the model already declared: the `text: "title"` search role
- * names exactly that field, so an agent-facing label costs no new declaration. Falls back to the conventional
- * `title`/`name` keys; the id is the caller's floor.
+ * The one line a human scans for. A model that writes its own `Light<Model>.label()` owns the answer, since
+ * display logic is the Light class's job; otherwise it is derived from what the model already declared — the
+ * `text: "title"` search role names exactly that field, so an agent-facing label costs no new declaration.
+ * Falls back to the conventional `title`/`name` keys; the id is the caller's floor.
  */
 export const labelOf = (model: unknown, value: unknown): string | undefined => {
   if (!value || typeof value !== "object") return undefined;
   const source = value as Record<string, unknown>;
+  const written = source.label;
+  if (typeof written === "function") {
+    try {
+      const label = (written as () => unknown).call(source);
+      if (typeof label === "string" && label) return label;
+    } catch {
+    }
+  }
   const paths = (model as { text?: { title?: Iterable<string> } } | null)?.text?.title;
   const titlePath = [...(paths ?? [])].find((path) => !path.includes(".") && !path.includes("["));
   for (const key of [titlePath, "title", "name"]) {

package/document/filterMeta.ts

@@ -275,7 +275,6 @@ interface ArgProps<Value = unknown> {
   nullable?: boolean;
   ref?: string;
   default?: Value;
-  renderOption?: (arg: never) => string;
 }
 export class FilterInfo<ArgNames extends string[] = any, Args extends any[] = any, Model = any> {
   readonly argNames: ArgNames = [] as unknown as ArgNames;

package/document/types.ts

@@ -21,7 +21,6 @@ export interface FilterArgProps {
   nullable?: boolean;
   ref?: string;
   default?: string | number | boolean | object | null | (() => string | number | boolean | object | null);
-  renderOption?: (value: never) => string;
   enum?: EnumInstance;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.60",
+  "version": "3.0.0-alpha.61",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/types/constant/labelOf.d.ts

@@ -1,6 +1,7 @@
 /**
- * The one line a human scans for, derived from what the model already declared: the `text: "title"` search role
- * names exactly that field, so an agent-facing label costs no new declaration. Falls back to the conventional
- * `title`/`name` keys; the id is the caller's floor.
+ * The one line a human scans for. A model that writes its own `Light<Model>.label()` owns the answer, since
+ * display logic is the Light class's job; otherwise it is derived from what the model already declared — the
+ * `text: "title"` search role names exactly that field, so an agent-facing label costs no new declaration.
+ * Falls back to the conventional `title`/`name` keys; the id is the caller's floor.
  */
 export declare const labelOf: (model: unknown, value: unknown) => string | undefined;

package/types/document/filterMeta.d.ts

@@ -117,7 +117,6 @@ interface ArgProps<Value = unknown> {
     nullable?: boolean;
     ref?: string;
     default?: Value;
-    renderOption?: (arg: never) => string;
 }
 export declare class FilterInfo<ArgNames extends string[] = any, Args extends any[] = any, Model = any> {
     readonly argNames: ArgNames;

package/types/document/types.d.ts

@@ -17,7 +17,6 @@ export interface FilterArgProps {
     nullable?: boolean;
     ref?: string;
     default?: string | number | boolean | object | null | (() => string | number | boolean | object | null);
-    renderOption?: (value: never) => string;
     enum?: EnumInstance;
 }
 export type DocumentProjection<T> = Partial<Record<keyof T, boolean>>;

package/types/ui/Data/QueryMaker.d.ts

@@ -1,8 +1,41 @@
 import type { QuerySetting, SliceMeta } from "akanjs/fetch";
+import type { SerializedArg } from "akanjs/signal";
 interface QueryMakerProps {
     className?: string;
     slice: SliceMeta;
     query?: QuerySetting;
+    /** Where a completed filter goes. Defaults to the slice's own store, which is where a listing reads it. */
+    onApply?: (setting: Required<QuerySetting>) => void;
 }
-export default function QueryMaker({ className, slice, query }: QueryMakerProps): import("react/jsx-runtime").JSX.Element | null;
+export interface QueryMakerState {
+    queryKeys: string[];
+    args: SerializedArg[];
+    setting: Required<QuerySetting>;
+    selectKey: (queryKey: string) => void;
+    setArg: (idx: number, value: unknown) => void;
+}
+interface QueryMakerKeyProps {
+    className?: string;
+    selectClassName?: string;
+    slice: SliceMeta;
+    state: QueryMakerState;
+}
+interface QueryMakerArgsProps {
+    className?: string;
+    slice: SliceMeta;
+    state: QueryMakerState;
+}
+/** A filter the server will accept: every arg it declared as required has been given a value. */
+export declare const isReadyQuery: (args: SerializedArg[], values: unknown[]) => boolean;
+/**
+ * The filter a listing is showing, and the one write that applies it. Held in a hook rather than a component
+ * because the key select rides the toolbar while the args that key takes render under it — two places in the
+ * tree, one selection.
+ */
+export declare const useQueryMaker: ({ slice, query, onApply }: QueryMakerProps) => QueryMakerState;
+/** The filter picker. Sized for a toolbar, beside the sort and page-size selects. */
+export declare const QueryMakerKey: ({ className, selectClassName, slice, state }: QueryMakerKeyProps) => import("react/jsx-runtime").JSX.Element | null;
+/** What the picked filter asks for. Renders nothing for a filter that takes no arguments. */
+export declare const QueryMakerArgs: ({ className, slice, state }: QueryMakerArgsProps) => import("react/jsx-runtime").JSX.Element | null;
+export default function QueryMaker({ className, slice, query, onApply }: QueryMakerProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/types/ui/Data/RefPicker.d.ts

@@ -0,0 +1,16 @@
+interface RefPickerProps {
+    className?: string;
+    /** The model this id points at, named by the filter arg's `ref`. */
+    refName: string;
+    value: string | null;
+    onChange: (id: string | null) => void;
+}
+/**
+ * Picks one row of a referenced model instead of asking for its hex id. Rows are held here rather than in the
+ * ref model's store: that store is a singleton, so a picker loading into it would overwrite whatever listing of
+ * the same model is already on the screen — and a picker opened from inside a picker would overwrite itself.
+ *
+ * The search is the ref model's own root slice, which is Admin-guarded, so this belongs to admin surfaces.
+ */
+export default function RefPicker({ className, refName, value, onChange }: RefPickerProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -6,5 +6,6 @@ export declare const Data: {
     ListContainer: typeof import("./ListContainer.d.ts").default;
     Pagination: typeof import("./Pagination.d.ts").default;
     QueryMaker: typeof import("./QueryMaker.d.ts").default;
+    RefPicker: typeof import("./RefPicker.d.ts").default;
     TableList: typeof import("./TableList.d.ts").default;
 };

package/types/ui/Data/index_.d.ts

@@ -6,3 +6,4 @@ export declare const ListContainer: typeof import("./ListContainer.d.ts").defaul
 export declare const Pagination: typeof import("./Pagination.d.ts").default;
 export declare const TableList: typeof import("./TableList.d.ts").default;
 export declare const QueryMaker: typeof import("./QueryMaker.d.ts").default;
+export declare const RefPicker: typeof import("./RefPicker.d.ts").default;

package/types/ui/Signal/Arg.d.ts

@@ -1,5 +1,6 @@
 import { type Dayjs, type DefaultPrimitiveName } from "akanjs/base";
 import type { SerializedArg } from "akanjs/signal";
+import type { ReactNode } from "react";
 interface ArgProps {
     argType: DefaultPrimitiveName;
     value: any;
@@ -9,7 +10,7 @@ declare function Arg({ argType, value, onChange }: ArgProps): import("react/jsx-
 declare namespace Arg {
     var Table: ({ refName, endpointKey, args }: ArgTableProps) => import("react/jsx-runtime").JSX.Element;
     var Param: ({ endpointKey, arg, value, onChange }: ArgParamProps) => import("react/jsx-runtime").JSX.Element;
-    var Query: ({ endpointKey, arg, label, value, onChange }: ArgQueryProps) => import("react/jsx-runtime").JSX.Element;
+    var Query: ({ endpointKey, arg, label, value, onChange, renderScalar }: ArgQueryProps) => import("react/jsx-runtime").JSX.Element;
     var FormData: ({ endpointKey, arg, value, onChange }: ArgFormDataProps) => import("react/jsx-runtime").JSX.Element;
     var ID: ({ value, onChange }: ArgIDProps) => import("react/jsx-runtime").JSX.Element;
     var Int: ({ value, onChange }: ArgIntProps) => import("react/jsx-runtime").JSX.Element;
@@ -38,6 +39,8 @@ interface ArgQueryProps {
     label?: string;
     value: any;
     onChange: (value: any) => void;
+    /** Replaces the scalar input this arg would otherwise get, once per element for an array arg. */
+    renderScalar?: (value: any, onChange: (value: any) => void) => ReactNode;
 }
 interface ArgFormDataProps {
     endpointKey: string;

package/ui/Data/ListContainer.tsx

@@ -36,7 +36,7 @@ import { Select } from "../Select";
 import DataCardList from "./CardList";
 import { columnKey, downloadBlob, toCsvBlob, toJsonBlob } from "./dataExport";
 import { dictLabel } from "./dataText";
-import DataQueryMaker from "./QueryMaker";
+import { QueryMakerArgs, QueryMakerKey, useQueryMaker } from "./QueryMaker";
 import DataTableList from "./TableList";
 
 const controlClassName = "h-9";
@@ -174,6 +174,7 @@ export default function ListContainer<
   const searchParams = st.use.searchParams({ agent: false });
   const filter = Array.isArray(searchParams.filter) ? searchParams.filter[0] : searchParams.filter;
   const initQuery = query ?? (filter ? queryMap?.[filter] : undefined);
+  const queryState = useQueryMaker({ slice, query: initQuery });
   useEffect(() => {
     
     const queryArgs = new Array(slice.argLength).fill(null) as unknown[];
@@ -261,9 +262,12 @@ export default function ListContainer<
     if (!Stat || !summary) return null;
     return summaryLoading ? <Loading.Skeleton className="mb-4" active /> : <Stat summary={summary} hidePresents />;
   };
-  
-  const RenderQueryMaker =
-    renderQueryMaker ?? (query ? undefined : () => <DataQueryMaker slice={slice} query={initQuery} />);
+
+  const queryMakerArgs = renderQueryMaker ? (
+    renderQueryMaker()
+  ) : query ? null : (
+    <QueryMakerArgs slice={slice} state={queryState} />
+  );
   const RenderInsight = (): ReactNode => (renderInsight ? renderInsight({ insight: modelInsight }) : null);
   const RenderTemplate = renderTemplate;
   const RenderTools = (): ReactNode => {
@@ -356,6 +360,14 @@ export default function ListContainer<
               </button>
             ))}
           </div>
+          {query ? null : (
+            <QueryMakerKey
+              className="w-44 min-w-0"
+              selectClassName={cn("min-h-0", controlClassName)}
+              slice={slice}
+              state={queryState}
+            />
+          )}
           <RenderSort />
           <Select<number>
             className="w-36 min-w-0"
@@ -390,7 +402,7 @@ export default function ListContainer<
         </div>
       </div>
       {query ? null : <ModelDashboard />}
-      {RenderQueryMaker ? <RenderQueryMaker /> : null}
+      {queryMakerArgs}
       <RenderInsight />
       {view === "card" ? (
         <DataCardList

package/ui/Data/QueryMaker.tsx

@@ -5,22 +5,53 @@ import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { SerializedArg } from "akanjs/signal";
 import { st } from "akanjs/store";
 import { useDebounce } from "akanjs/webkit";
-import { useState } from "react";
+import { useRef, useState } from "react";
 import { Select } from "../Select";
 import Arg from "../Signal/Arg";
 import { dictLabel } from "./dataText";
+import RefPicker from "./RefPicker";
 
 interface QueryMakerProps {
   className?: string;
   slice: SliceMeta;
   query?: QuerySetting;
+  /** Where a completed filter goes. Defaults to the slice's own store, which is where a listing reads it. */
+  onApply?: (setting: Required<QuerySetting>) => void;
+}
+export interface QueryMakerState {
+  queryKeys: string[];
+  args: SerializedArg[];
+  setting: Required<QuerySetting>;
+  selectKey: (queryKey: string) => void;
+  setArg: (idx: number, value: unknown) => void;
+}
+interface QueryMakerKeyProps {
+  className?: string;
+  selectClassName?: string;
+  slice: SliceMeta;
+  state: QueryMakerState;
+}
+interface QueryMakerArgsProps {
+  className?: string;
+  slice: SliceMeta;
+  state: QueryMakerState;
 }
 
 const isFillableArg = (arg: SerializedArg) => !arg.modelType;
 const defaultArg = (arg: SerializedArg) => ((arg.arrDepth ?? 0) > 0 ? [] : null);
 
-export default function QueryMaker({ className, slice, query }: QueryMakerProps) {
-  const { l } = usePage();
+const isFilledArg = (value: unknown) =>
+  value !== null && value !== undefined && value !== "" && !(Array.isArray(value) && !value.length);
+/** A filter the server will accept: every arg it declared as required has been given a value. */
+export const isReadyQuery = (args: SerializedArg[], values: unknown[]) =>
+  args.every((arg, idx) => arg.nullable || isFilledArg(values[idx]));
+
+/**
+ * The filter a listing is showing, and the one write that applies it. Held in a hook rather than a component
+ * because the key select rides the toolbar while the args that key takes render under it — two places in the
+ * tree, one selection.
+ */
+export const useQueryMaker = ({ slice, query, onApply }: QueryMakerProps): QueryMakerState => {
   const { refName, sliceName } = slice;
   const storeDo = st.do as unknown as { [key: string]: (...args: unknown[]) => Promise<void> };
   const filterQuery = fetch.filterQueryMap?.get(refName) ?? {};
@@ -31,41 +62,94 @@ export default function QueryMaker({ className, slice, query }: QueryMakerProps)
     queryKey: query?.queryKey ?? queryKeys[0] ?? "any",
     args: query?.args ?? [],
   });
+
+  const applyRef = useRef<(setting: Required<QuerySetting>) => void>(() => undefined);
+  applyRef.current = (setting) => {
+    if (onApply) onApply(setting);
+    else void storeDo[`setQueryArgsOf${capitalize(sliceName)}`](setting.queryKey, setting.args);
+  };
   
   const applyQuery = useDebounce((setting: Required<QuerySetting>) => {
-    void storeDo[`setQueryArgsOf${capitalize(sliceName)}`](setting.queryKey, setting.args);
+    applyRef.current(setting);
   }, []);
   const update = (setting: Required<QuerySetting>) => {
     setSetting(setting);
-    applyQuery(setting);
+
+    if (isReadyQuery(filterQuery[setting.queryKey] ?? [], setting.args)) applyQuery(setting);
   };
   const args = filterQuery[setting.queryKey] ?? [];
+  return {
+    queryKeys,
+    args,
+    setting,
+    selectKey: (queryKey) => {
+      update({ queryKey, args: (filterQuery[queryKey] ?? []).map(defaultArg) });
+    },
+    setArg: (idx, value) => {
+      update({ ...setting, args: args.map((arg, i) => (i === idx ? value : (setting.args[i] ?? defaultArg(arg)))) });
+    },
+  };
+};
+
+/** The filter picker. Sized for a toolbar, beside the sort and page-size selects. */
+export const QueryMakerKey = ({ className, selectClassName, slice, state }: QueryMakerKeyProps) => {
+  const { l } = usePage();
+  const { queryKeys, setting, selectKey } = state;
   if (queryKeys.length < 2) return null;
+  return (
+    <Select<string>
+      className={className}
+      selectClassName={selectClassName}
+      value={setting.queryKey}
+      options={queryKeys.map((queryKey) => ({
+        label: dictLabel(l._, `${slice.refName}.query.${queryKey}`, queryKey),
+        value: queryKey,
+      }))}
+      onChange={selectKey}
+    />
+  );
+};
+
+/** What the picked filter asks for. Renders nothing for a filter that takes no arguments. */
+export const QueryMakerArgs = ({ className, slice, state }: QueryMakerArgsProps) => {
+  const { l } = usePage();
+  const { args, setting, setArg } = state;
+  if (!args.length) return null;
   return (
     <div className={cn("mb-4 flex w-full flex-col gap-1 rounded-box border border-border p-3", className)}>
-      <Select<string>
-        className="w-full md:w-72"
-        value={setting.queryKey}
-        options={queryKeys.map((queryKey) => ({
-          label: dictLabel(l._, `${refName}.query.${queryKey}`, queryKey),
-          value: queryKey,
-        }))}
-        onChange={(queryKey) => {
-          update({ queryKey, args: (filterQuery[queryKey] ?? []).map(defaultArg) });
-        }}
-      />
-      {args.map((arg, idx) => (
-        <Arg.Query
-          key={arg.name}
-          endpointKey={setting.queryKey}
-          arg={arg}
-          label={dictLabel(l._, `${refName}.query.${setting.queryKey}.arg.${arg.name}`, arg.name)}
-          value={setting.args[idx] ?? defaultArg(arg)}
-          onChange={(value: unknown) => {
-            update({ ...setting, args: args.map((a, i) => (i === idx ? value : (setting.args[i] ?? defaultArg(a)))) });
-          }}
-        />
-      ))}
+      {args.map((arg, idx) => {
+
+        const ref = arg.ref && fetch.slice[arg.ref] ? arg.ref : undefined;
+        return (
+          <Arg.Query
+            key={arg.name}
+            endpointKey={setting.queryKey}
+            arg={arg}
+            label={dictLabel(l._, `${slice.refName}.query.${setting.queryKey}.arg.${arg.name}`, arg.name)}
+            value={setting.args[idx] ?? defaultArg(arg)}
+            onChange={(value: unknown) => {
+              setArg(idx, value);
+            }}
+            renderScalar={
+              ref
+                ? (value: string | null, onChange: (value: string | null) => void) => (
+                    <RefPicker refName={ref} value={value} onChange={onChange} />
+                  )
+                : undefined
+            }
+          />
+        );
+      })}
+    </div>
+  );
+};
+
+export default function QueryMaker({ className, slice, query, onApply }: QueryMakerProps) {
+  const state = useQueryMaker({ slice, query, onApply });
+  return (
+    <div className={cn("flex w-full flex-col gap-1", className)}>
+      <QueryMakerKey className="w-full md:w-72" slice={slice} state={state} />
+      <QueryMakerArgs slice={slice} state={state} />
     </div>
   );
 }

package/ui/Data/RefPicker.tsx

@@ -0,0 +1,203 @@
+"use client";
+import { cn, fetch, usePage } from "akanjs/client";
+import { capitalize } from "akanjs/common";
+import { ConstantRegistry, labelOf } from "akanjs/constant";
+import type { QuerySetting } from "akanjs/fetch";
+import { useEffect, useState } from "react";
+import { AiOutlineClose, AiOutlineSearch } from "react-icons/ai";
+import { buttonRecipe } from "../Button";
+import { Empty } from "../Empty";
+import { Loading } from "../Loading";
+import { Modal } from "../Modal";
+import { dictLabel } from "./dataText";
+import { isReadyQuery, QueryMakerArgs, QueryMakerKey, useQueryMaker } from "./QueryMaker";
+
+interface RefPickerProps {
+  className?: string;
+  /** The model this id points at, named by the filter arg's `ref`. */
+  refName: string;
+  value: string | null;
+  onChange: (id: string | null) => void;
+}
+interface RefRow {
+  id: string;
+  label?: string;
+}
+
+const pageSize = 20;
+
+/**
+ * Picks one row of a referenced model instead of asking for its hex id. Rows are held here rather than in the
+ * ref model's store: that store is a singleton, so a picker loading into it would overwrite whatever listing of
+ * the same model is already on the screen — and a picker opened from inside a picker would overwrite itself.
+ *
+ * The search is the ref model's own root slice, which is Admin-guarded, so this belongs to admin surfaces.
+ */
+export default function RefPicker({ className, refName, value, onChange }: RefPickerProps) {
+  const { l } = usePage();
+  const slice = fetch.slice[refName];
+  const filterQuery = fetch.filterQueryMap?.get(refName) ?? {};
+
+  const initialKey = filterQuery.bySearch ? "bySearch" : "any";
+  const initialQuery: Required<QuerySetting> = { queryKey: initialKey, args: [] };
+
+  const [open, setOpen] = useState(false);
+  const [applied, setApplied] = useState<Required<QuerySetting>>(initialQuery);
+  const [page, setPage] = useState(1);
+  const [rows, setRows] = useState<RefRow[]>([]);
+  const [hasNext, setHasNext] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [picked, setPicked] = useState<RefRow | null>(null);
+
+  const state = useQueryMaker({
+    slice,
+    query: initialQuery,
+    onApply: (setting) => {
+      setPage(1);
+      setApplied(setting);
+    },
+  });
+
+  useEffect(() => {
+    if (!open) return;
+    if (!isReadyQuery(filterQuery[applied.queryKey] ?? [], applied.args)) {
+      setRows([]);
+      return;
+    }
+    const listFn = fetch[`${refName}List`] as (...args: unknown[]) => Promise<Record<string, unknown>[]>;
+    const cnst = ConstantRegistry.getDatabase(refName);
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    
+    void listFn(applied.queryKey, applied.args, (page - 1) * pageSize, pageSize + 1, "latest")
+      .then((list) => {
+        if (cancelled) return;
+        setHasNext(list.length > pageSize);
+        setRows(list.slice(0, pageSize).map((row) => ({ id: String(row.id), label: labelOf(cnst.full, row) })));
+      })
+      .catch((reason: unknown) => {
+        if (cancelled) return;
+        setRows([]);
+        setError(reason instanceof Error ? reason.message : String(reason));
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [open, applied, page, refName]);
+
+  const modelLabel = dictLabel(l._, `${refName}.modelName`, refName);
+  const selectLabel = l.trans({ en: `Select ${modelLabel}`, ko: `${modelLabel} 선택` });
+  const selected = picked?.id === value ? picked.label : undefined;
+  const unlabeled = !!rows.length && rows.every((row) => !row.label);
+
+  return (
+    <div className={cn("flex w-full items-center gap-2", className)}>
+      <button
+        className={buttonRecipe({ variant: "outline", size: "sm" }, "min-w-0 flex-1 justify-start")}
+        onClick={() => {
+          setOpen(true);
+        }}
+        type="button"
+      >
+        <AiOutlineSearch className="shrink-0 text-foreground/50" />
+        <span className={cn("truncate", value ? (selected ? "" : "font-mono") : "text-foreground/45")}>
+          {selected ?? value ?? selectLabel}
+        </span>
+      </button>
+      {value ? (
+        <button
+          className={buttonRecipe({ variant: "ghost", size: "icon" }, "size-8 shrink-0 text-foreground/50")}
+          onClick={() => {
+            setPicked(null);
+            onChange(null);
+          }}
+          type="button"
+        >
+          <AiOutlineClose />
+        </button>
+      ) : null}
+      <Modal
+        className="max-w-xl"
+        open={open}
+        onCancel={() => {
+          setOpen(false);
+        }}
+        title={selectLabel}
+      >
+        <div className="flex flex-col gap-2">
+          <QueryMakerKey slice={slice} state={state} />
+          <QueryMakerArgs className="mb-0" slice={slice} state={state} />
+          {error ? (
+            <div className="rounded-box border border-destructive/30 bg-destructive/10 px-3 py-2 text-destructive text-xs">
+              {error}
+            </div>
+          ) : null}
+          {unlabeled ? (
+            <div className="rounded-box border border-warning/30 bg-warning/10 px-3 py-2 text-foreground/70 text-xs">
+              {l.trans({
+                en: `These rows show their id because "${refName}" has no label. Add a label() method to Light${capitalize(refName)}, or mark one field with { text: "title" }.`,
+                ko: `"${refName}"에 라벨이 없어 id를 표시합니다. Light${capitalize(refName)}에 label() 메서드를 추가하거나 필드 하나에 { text: "title" }을 지정하세요.`,
+              })}
+            </div>
+          ) : null}
+          {loading ? (
+            <Loading.Skeleton active />
+          ) : rows.length ? (
+            <div className="flex flex-col divide-y divide-border">
+              {rows.map((row) => (
+                <button
+                  className={cn(
+                    "flex items-center justify-between gap-3 px-2 py-2.5 text-left hover:bg-muted",
+                    row.id === value && "bg-primary/10",
+                  )}
+                  key={row.id}
+                  onClick={() => {
+                    setPicked(row);
+                    onChange(row.id);
+                    setOpen(false);
+                  }}
+                  type="button"
+                >
+                  <span className={cn("min-w-0 truncate text-sm", row.label ? "" : "font-mono")}>
+                    {row.label ?? row.id}
+                  </span>
+                  {row.label ? <span className="shrink-0 font-mono text-foreground/40 text-xs">{row.id}</span> : null}
+                </button>
+              ))}
+            </div>
+          ) : (
+            <Empty minHeight={160} />
+          )}
+          <div className="flex items-center justify-between gap-2 pt-1">
+            <button
+              className={buttonRecipe({ variant: "ghost", size: "sm" })}
+              disabled={page <= 1}
+              onClick={() => {
+                setPage(page - 1);
+              }}
+              type="button"
+            >
+              {l.trans({ en: "Prev", ko: "이전" })}
+            </button>
+            <span className="text-foreground/45 text-xs">{page}</span>
+            <button
+              className={buttonRecipe({ variant: "ghost", size: "sm" })}
+              disabled={!hasNext}
+              onClick={() => {
+                setPage(page + 1);
+              }}
+              type="button"
+            >
+              {l.trans({ en: "Next", ko: "다음" })}
+            </button>
+          </div>
+        </div>
+      </Modal>
+    </div>
+  );
+}

package/ui/Data/index.ts

@@ -1,4 +1,14 @@
-import { CardList, Dashboard, Insight, Item, ListContainer, Pagination, QueryMaker, TableList } from "./index_";
+import {
+  CardList,
+  Dashboard,
+  Insight,
+  Item,
+  ListContainer,
+  Pagination,
+  QueryMaker,
+  RefPicker,
+  TableList,
+} from "./index_";
 
 export const Data = {
   CardList,
@@ -8,5 +18,6 @@ export const Data = {
   ListContainer,
   Pagination,
   QueryMaker,
+  RefPicker,
   TableList,
 };

package/ui/Data/index_.tsx

@@ -9,3 +9,4 @@ export const ListContainer = lazy(() => import("./ListContainer"));
 export const Pagination = lazy(() => import("./Pagination"));
 export const TableList = lazy(() => import("./TableList"));
 export const QueryMaker = lazy(() => import("./QueryMaker"));
+export const RefPicker = lazy(() => import("./RefPicker"));

package/ui/Signal/Arg.tsx

@@ -4,7 +4,7 @@ import { usePage } from "akanjs/client";
 import { type ConstantCls, ConstantRegistry } from "akanjs/constant";
 import type { SerializedArg } from "akanjs/signal";
 import { st } from "akanjs/store";
-import type { ChangeEvent } from "react";
+import type { ChangeEvent, ReactNode } from "react";
 import { AiOutlineDelete, AiOutlinePlus } from "react-icons/ai";
 import { buttonRecipe } from "../Button";
 import { DatePicker } from "../DatePicker";
@@ -141,8 +141,10 @@ interface ArgQueryProps {
   label?: string;
   value: any;
   onChange: (value: any) => void;
+  /** Replaces the scalar input this arg would otherwise get, once per element for an array arg. */
+  renderScalar?: (value: any, onChange: (value: any) => void) => ReactNode;
 }
-const ArgQuery = ({ endpointKey, arg, label, value, onChange }: ArgQueryProps) => {
+const ArgQuery = ({ endpointKey, arg, label, value, onChange, renderScalar }: ArgQueryProps) => {
   const argRef = ConstantRegistry.getModelRef(arg.refName, arg.modelType);
   if (!PrimitiveRegistry.has(argRef)) throw new Error(`Query arg - ${endpointKey}/${arg.name} must be scalar`);
   else if ((arg.arrDepth ?? 0) > 1)
@@ -151,6 +153,12 @@ const ArgQuery = ({ endpointKey, arg, label, value, onChange }: ArgQueryProps) =
   const enumRef = arg.enum ? ConstantRegistry.enum.get(arg.enum) : undefined;
   const options: (string | number)[] = arg.oneOf ?? (enumRef ? [...enumRef.values] : []);
   const multiple = (arg.arrDepth ?? 0) > 0;
+  const renderLeaf = (leafValue: unknown, onLeafChange: (value: unknown) => void) =>
+    renderScalar ? (
+      renderScalar(leafValue, onLeafChange)
+    ) : (
+      <Arg argType={argType} value={leafValue as string} onChange={onLeafChange} />
+    );
   return (
     <div className={signalUi.inputRow}>
       <div className={signalUi.inputLabel}>{label ?? arg.name}</div>
@@ -167,13 +175,9 @@ const ArgQuery = ({ endpointKey, arg, label, value, onChange }: ArgQueryProps) =
           <div className="flex flex-col gap-2">
             {value.map((val, idx) => (
               <div className="flex items-center gap-2" key={idx}>
-                <Arg
-                  argType={argType}
-                  value={val as string}
-                  onChange={(val) => {
-                    onChange([...(value.slice(0, idx) as string[]), val, ...(value.slice(idx + 1) as string[])]);
-                  }}
-                />
+                {renderLeaf(val, (val) => {
+                  onChange([...(value.slice(0, idx) as string[]), val, ...(value.slice(idx + 1) as string[])]);
+                })}
                 <button
                   className={buttonRecipe({ variant: "ghost", size: "icon" }, "size-8 shrink-0 text-foreground/50")}
                   onClick={() => {
@@ -196,7 +200,7 @@ const ArgQuery = ({ endpointKey, arg, label, value, onChange }: ArgQueryProps) =
             </button>
           </div>
         ) : (
-          <Arg argType={argType} value={value as string} onChange={onChange} />
+          renderLeaf(value, onChange)
         )}
       </div>
     </div>