akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/ui/Field/Relation.tsx

@@ -1,37 +1,48 @@
 "use client";
 import type { DataList } from "akanjs/base";
 import { cn } from "akanjs/client";
-import { capitalize, lowerlize } from "akanjs/common";
 import type { SliceMeta } from "akanjs/fetch";
-import { st, useFieldTool, useRelationFieldTool } from "akanjs/store";
+import { useFieldTool, useRelationFieldTool } from "akanjs/store";
 import type { ReactNode } from "react";
 import { agentAttrs } from "../agentAttrs";
 import { Select } from "../Select";
 import { Label } from "./Label";
+import { useRelationOptions } from "./useRelationOptions";
 
-export interface ParentProps<Light> {
+interface UnresolvedProps {
+  id: string;
+}
+/** A row nothing could resolve — removed, unreadable, or still being read. The id beats an empty control. */
+const Unresolved = ({ id }: UnresolvedProps) => <span className="font-mono text-foreground/45">{id}</span>;
+
+const renderRow = <Light extends { id: string }>(
+  models: DataList<Light>,
+  id: string,
+  render: (model: Light) => ReactNode,
+) => {
+  const model = models.get(id);
+  return model ? render(model) : <Unresolved id={id} />;
+};
+
+interface RelationProps<Light> {
   label?: string;
   desc?: string;
   labelClassName?: string;
-  selectClassName?: string;
   className?: string;
   disabled?: boolean;
   nullable?: boolean;
   initArgs?: any[];
-  value: Light | null;
   slice: SliceMeta;
-  onChange: (value: Light | null) => void;
   onSearch?: (text: string) => void;
   sortOption?: (a: Light, b: Light) => number;
+}
+export interface ParentProps<Light> extends RelationProps<Light> {
+  selectClassName?: string;
+  value: Light | null;
+  onChange: (value: Light | null) => void;
   renderOption: (model: Light) => ReactNode;
   renderSelected?: (value: Light) => ReactNode;
 }
-/** The one line an option renders as, so an agent can match an id against what it reads on screen. */
-const optionLabel = <Light extends { id: string }>(model: Light, render: (model: Light) => ReactNode) => {
-  const rendered = render(model);
-  return typeof rendered === "string" ? rendered : model.id;
-};
-
 export const Parent = <Light extends { id: string }>({
   label,
   desc,
@@ -49,32 +60,15 @@ export const Parent = <Light extends { id: string }>({
   renderOption,
   renderSelected = renderOption,
 }: ParentProps<Light>) => {
-  const { refName, sliceName } = slice;
-  const [modelName, ModelName] = [lowerlize(refName), capitalize(refName)];
-  const storeUse = st.use as { [key: string]: () => unknown };
-  const storeDo = st.do as unknown as { [key: string]: (...args: any[]) => Promise<void> };
-  const storeGet = st.get as unknown as <V>() => { [key: string]: V };
-
-  const names = {
-    model: modelName,
-    modelList: `${modelName}List`,
-    modelListLoading: `${modelName}ListLoading`,
-    refreshModel: `refresh${ModelName}`,
-  };
-
-  const namesOfSlice = {
-    modelList: sliceName.replace(names.model, names.modelList),
-    modelListLoading: sliceName.replace(names.model, names.modelListLoading),
-    refreshModel: sliceName.replace(names.model, names.refreshModel),
-  };
-
-  const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
-  useRelationFieldTool(onChange, {
-    read: () => storeGet<DataList<Light>>()[namesOfSlice.modelList],
-    load: () => storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs }),
-    label: (model) => optionLabel(model, renderOption),
-    disabled,
+  const { models, options, optionLabel, listLoading, load, read } = useRelationOptions<Light>({
+    slice,
+    ids: value ? [value.id] : [],
+    pinned: [value],
+    initArgs,
+    sortOption,
+    renderOption,
   });
+  useRelationFieldTool(onChange, { read, load, label: optionLabel, disabled });
 
   return (
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
@@ -84,50 +78,24 @@ export const Parent = <Light extends { id: string }>({
         selectClassName={selectClassName}
         value={value?.id ?? null}
         searchable
-        options={modelList.map((model) => {
-          const render = renderOption(model);
-          return { label: typeof render === "string" ? render : model.id, value: model.id };
-        })}
-        renderOption={(modelId) => {
-          if (!modelId) return null;
-          const model = modelList.get(modelId);
-          if (!model) return null;
-          return renderOption(model);
-        }}
-        renderSelected={(modelId) => {
-          if (!modelId) return null;
-          const model = modelList.get(modelId);
-          if (!model) return null;
-          return renderSelected(model);
-        }}
+        loading={listLoading}
+        options={options}
+        renderOption={(modelId) => (modelId ? renderRow(models, modelId, renderOption) : null)}
+        renderSelected={(modelId) => (modelId ? renderRow(models, modelId, renderSelected) : null)}
         onChange={(modelId) => {
-          if (modelId) onChange(modelList.get(modelId) ?? null);
-          else onChange(null);
-        }}
-        onOpen={() => {
-          if (disabled) return;
-          void storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs });
+          onChange(modelId ? (models.get(modelId) ?? null) : null);
         }}
+        onOpen={disabled ? undefined : load}
         onSearch={onSearch}
       />
     </div>
   );
 };
 
-export interface ParentIdProps<Light> {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
-  className?: string;
+export interface ParentIdProps<Light> extends RelationProps<Light> {
   selectClassName?: string;
-  disabled?: boolean;
-  nullable?: boolean;
-  initArgs?: any[];
   value: string | null;
-  slice: SliceMeta;
   onChange: (id: string | null, model: Light | null) => void;
-  onSearch?: (text: string) => void;
-  sortOption?: (a: Light, b: Light) => number;
   renderOption?: (model: Light) => ReactNode;
   renderSelected?: (value: Light) => ReactNode;
 }
@@ -148,22 +116,13 @@ export const ParentId = <Light extends { id: string }>({
   renderOption,
   renderSelected = renderOption,
 }: ParentIdProps<Light>) => {
-  const { refName, sliceName } = slice;
-  const [modelName, ModelName] = [lowerlize(refName), capitalize(refName)];
-  const storeUse = st.use as { [key: string]: () => unknown };
-  const storeDo = st.do as unknown as { [key: string]: (...args: any[]) => Promise<void> };
-  const names = {
-    model: modelName,
-    modelList: `${modelName}List`,
-    modelListLoading: `${modelName}ListLoading`,
-    refreshModel: `refresh${ModelName}`,
-  };
-  const namesOfSlice = {
-    modelList: sliceName.replace(names.model, names.modelList),
-    modelListLoading: sliceName.replace(names.model, names.modelListLoading),
-    refreshModel: sliceName.replace(names.model, names.refreshModel),
-  };
-  const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
+  const { models, options, optionLabel, listLoading, load } = useRelationOptions<Light>({
+    slice,
+    ids: value ? [value] : [],
+    initArgs,
+    sortOption,
+    renderOption,
+  });
   
   useFieldTool(onChange, { disabled });
 
@@ -175,25 +134,13 @@ export const ParentId = <Light extends { id: string }>({
         searchable
         selectClassName={selectClassName}
         value={value}
-        options={modelList.map((model) => model.id)}
-        renderOption={(renderId) => {
-          if (!renderId) return null;
-          const model = modelList.get(renderId);
-          if (!model) return null;
-          return renderOption?.(model) ?? null;
-        }}
-        renderSelected={(renderId) => {
-          if (!renderId) return null;
-          const model = modelList.get(renderId);
-          if (!model) return null;
-          return renderSelected?.(model) ?? null;
-        }}
-        onOpen={() => {
-          if (disabled) return;
-          void storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs });
-        }}
+        loading={listLoading}
+        options={options}
+        renderOption={(renderId) => (renderId ? renderRow(models, renderId, renderOption ?? optionLabel) : null)}
+        renderSelected={(renderId) => (renderId ? renderRow(models, renderId, renderSelected ?? optionLabel) : null)}
+        onOpen={disabled ? undefined : load}
         onChange={(modelId) => {
-          if (modelId) onChange(modelId, modelList.get(modelId) ?? null);
+          if (modelId) onChange(modelId, models.get(modelId) ?? null);
           else onChange(null, null);
         }}
         onSearch={onSearch}
@@ -202,20 +149,10 @@ export const ParentId = <Light extends { id: string }>({
   );
 };
 
-export interface ChildrenProps<Light> {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
+export interface ChildrenProps<Light> extends RelationProps<Light> {
   selectClassName?: string;
-  className?: string;
-  disabled?: boolean;
-  nullable?: boolean;
-  initArgs?: any[];
   value: Light[] | null;
   onChange: (value: Light[]) => void;
-  onSearch?: (text: string) => void;
-  slice: SliceMeta;
-  sortOption?: (a: Light, b: Light) => number;
   renderOption: (model: Light) => ReactNode;
   renderSelected?: (value: Light) => ReactNode;
 }
@@ -236,29 +173,15 @@ export const Children = <Light extends { id: string }>({
   renderOption,
   renderSelected = renderOption,
 }: ChildrenProps<Light>) => {
-  const { refName, sliceName } = slice;
-  const [modelName, ModelName] = [lowerlize(refName), capitalize(refName)];
-  const storeUse = st.use as { [key: string]: () => unknown };
-  const storeDo = st.do as unknown as { [key: string]: (...args: any[]) => Promise<void> };
-  const storeGet = st.get as unknown as <T>() => { [key: string]: T };
-  const names = {
-    model: modelName,
-    modelList: `${modelName}List`,
-    modelListLoading: `${modelName}ListLoading`,
-    refreshModel: `refresh${ModelName}`,
-  };
-  const namesOfSlice = {
-    modelList: sliceName.replace(names.model, names.modelList),
-    modelListLoading: sliceName.replace(names.model, names.modelListLoading),
-    refreshModel: sliceName.replace(names.model, names.refreshModel),
-  };
-  const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
-  useRelationFieldTool(onChange, {
-    read: () => storeGet<DataList<Light>>()[namesOfSlice.modelList],
-    load: () => storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs }),
-    label: (model) => optionLabel(model, renderOption),
-    disabled,
+  const { models, options, optionLabel, listLoading, load, read } = useRelationOptions<Light>({
+    slice,
+    ids: (value ?? []).map((model) => model.id),
+    pinned: value ?? [],
+    initArgs,
+    sortOption,
+    renderOption,
   });
+  useRelationFieldTool(onChange, { read, load, label: optionLabel, disabled });
 
   return (
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
@@ -269,28 +192,13 @@ export const Children = <Light extends { id: string }>({
         selectClassName={selectClassName}
         multiple
         value={(value ?? []).map((model) => model.id)}
-        options={modelList.map((model) => {
-          const label = renderOption(model);
-          return { label: typeof label === "string" ? label : model.id, value: model.id };
-        })}
-        onOpen={() => {
-          if (disabled) return;
-          void storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs });
-        }}
-        renderOption={(modelId: string) => {
-          const model = modelList.get(modelId);
-          if (!model) return null;
-          return renderOption(model);
-        }}
-        renderSelected={(modelId: string) => {
-          const model = modelList.get(modelId);
-          if (!model) return null;
-          return renderSelected(model);
-        }}
+        loading={listLoading}
+        options={options}
+        onOpen={disabled ? undefined : load}
+        renderOption={(modelId: string) => renderRow(models, modelId, renderOption)}
+        renderSelected={(modelId: string) => renderRow(models, modelId, renderSelected)}
         onChange={(modelIds: string[]) => {
-          onChange(
-            modelIds.map((id) => modelList.get(id)).filter((model) => model !== undefined) as unknown as Light[],
-          );
+          onChange(modelIds.map((id) => models.get(id)).filter((model): model is Light => !!model));
         }}
         onSearch={onSearch}
       />
@@ -298,19 +206,9 @@ export const Children = <Light extends { id: string }>({
   );
 };
 
-export interface ChildrenIdProps<Light> {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
-  className?: string;
-  disabled?: boolean;
-  nullable?: boolean;
-  initArgs?: any[];
+export interface ChildrenIdProps<Light> extends RelationProps<Light> {
   value: string[] | null;
-  slice: SliceMeta;
   onChange: (value: string[]) => void;
-  onSearch?: (text: string) => void;
-  sortOption?: (a: Light, b: Light) => number;
   renderOption: (model: Light) => ReactNode;
 }
 export const ChildrenId = <Light extends { id: string }>({
@@ -328,22 +226,13 @@ export const ChildrenId = <Light extends { id: string }>({
   sortOption,
   renderOption,
 }: ChildrenIdProps<Light>) => {
-  const { refName, sliceName } = slice;
-  const [modelName, ModelName] = [lowerlize(refName), capitalize(refName)];
-  const storeUse = st.use as { [key: string]: () => unknown };
-  const storeDo = st.do as unknown as { [key: string]: (...args: any[]) => Promise<void> };
-  const names = {
-    model: modelName,
-    modelList: `${modelName}List`,
-    modelListLoading: `${modelName}ListLoading`,
-    refreshModel: `refresh${ModelName}`,
-  };
-  const namesOfSlice = {
-    modelList: sliceName.replace(names.model, names.modelList),
-    modelListLoading: sliceName.replace(names.model, names.modelListLoading),
-    refreshModel: sliceName.replace(names.model, names.refreshModel),
-  };
-  const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
+  const { models, options, listLoading, load } = useRelationOptions<Light>({
+    slice,
+    ids: value ?? [],
+    initArgs,
+    sortOption,
+    renderOption,
+  });
   
   useFieldTool(onChange, { disabled });
 
@@ -354,21 +243,12 @@ export const ChildrenId = <Light extends { id: string }>({
         nullable={nullable}
         searchable
         multiple
-        
         value={value ?? []}
-        options={modelList.map((model) => {
-          const label = renderOption(model);
-          return { label: typeof label === "string" ? label : model.id, value: model.id };
-        })}
-        renderOption={(renderId) => {
-          const model = modelList.get(renderId);
-          if (!model) return null;
-          return renderOption(model);
-        }}
-        onOpen={() => {
-          if (disabled) return;
-          void storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs });
-        }}
+        loading={listLoading}
+        options={options}
+        renderOption={(renderId: string) => renderRow(models, renderId, renderOption)}
+        renderSelected={(renderId: string) => renderRow(models, renderId, renderOption)}
+        onOpen={disabled ? undefined : load}
         onChange={(modelIds) => {
           onChange(modelIds);
         }}

package/ui/Field/Text.tsx

@@ -6,7 +6,21 @@ import { agentAttrs } from "../agentAttrs";
 import { Input } from "../Input";
 import { Label } from "./Label";
 
-export interface TextProps {
+export const lengthValidator =
+  (
+    l: (key: string, param?: Record<string, string | number>) => string,
+    minlength: number,
+    maxlength: number,
+    validate?: (text: string) => boolean | string,
+  ) =>
+  (text: string) =>
+    text.length < minlength
+      ? l("base.textTooShortError", { minlength })
+      : text.length > maxlength
+        ? l("base.textTooLongError", { maxlength })
+        : (validate?.(text) ?? true);
+
+interface TextFieldProps {
   label?: string;
   desc?: string;
   labelClassName?: string;
@@ -22,6 +36,8 @@ export interface TextProps {
   minlength?: number;
   maxlength?: number;
   onPressEnter?: () => void;
+}
+export interface TextProps extends TextFieldProps {
   inputStyleType?: "bordered" | "borderless" | "underline";
 }
 export const Text = ({
@@ -59,34 +75,15 @@ export const Text = ({
         disabled={disabled}
         className={cn("w-full", "")}
         inputClassName={cn("w-full focus:border-primary", inputClassName)}
-        validate={(text: string) => {
-          if (text.length < minlength) return l("base.textTooShortError", { minlength });
-          else if (text.length > maxlength) return l("base.textTooLongError", { maxlength });
-          else return validate?.(text) ?? true;
-        }}
+        validate={lengthValidator(l, minlength, maxlength, validate)}
         onPressEnter={onPressEnter}
       />
     </div>
   );
 };
 
-export interface TextAreaProps {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
-  className?: string;
-  value: string | null;
-  onChange: (value: string) => void;
-  inputClassName?: string;
-  placeholder?: string;
-  nullable?: boolean;
-  disabled?: boolean;
-  transform?: (value: string) => string;
-  validate?: (text: string) => boolean | string;
+export interface TextAreaProps extends TextFieldProps {
   rows?: number;
-  minlength?: number;
-  maxlength?: number;
-  onPressEnter?: () => void;
 }
 export const TextArea = ({
   label,
@@ -123,33 +120,14 @@ export const TextArea = ({
         rows={rows}
         className={cn("h-full w-full")}
         inputClassName={cn("w-full focus:border-primary", inputClassName)}
-        validate={(text: string) => {
-          if (text.length < minlength) return l("base.textTooShortError", { minlength });
-          else if (text.length > maxlength) return l("base.textTooLongError", { maxlength });
-          else return validate?.(text) ?? true;
-        }}
+        validate={lengthValidator(l, minlength, maxlength, validate)}
         onPressEnter={onPressEnter}
       />
     </div>
   );
 };
 
-export interface EmailProps {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
-  className?: string;
-  value: string | null;
-  onChange: (value: string) => void;
-  inputClassName?: string;
-  placeholder?: string;
-  nullable?: boolean;
-  disabled?: boolean;
-  transform?: (value: string) => string;
-  validate?: (text: string) => boolean | string;
-  minlength?: number;
-  maxlength?: number;
-  onPressEnter?: () => void;
+export interface EmailProps extends TextFieldProps {
   inputStyleType?: "bordered" | "borderless" | "underline";
 }
 export const Email = ({
@@ -187,34 +165,14 @@ export const Email = ({
         className={cn("w-full", "")}
         inputClassName={cn("w-full focus:border-primary", inputClassName)}
         inputStyleType={inputStyleType}
-        validate={(text: string) => {
-          if (text.length < minlength) return l("base.textTooShortError", { minlength });
-          else if (text.length > maxlength) return l("base.textTooLongError", { maxlength });
-          else return validate?.(text) ?? true;
-        }}
+        validate={lengthValidator(l, minlength, maxlength, validate)}
         onPressEnter={onPressEnter}
       />
     </div>
   );
 };
 
-export interface PhoneProps {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
-  className?: string;
-  value: string | null;
-  onChange: (value: string) => void;
-  inputClassName?: string;
-  placeholder?: string;
-  nullable?: boolean;
-  disabled?: boolean;
-  transform?: (value: string) => string;
-  validate?: (text: string) => boolean | string;
-  minlength?: number;
-  maxlength?: number;
-  onPressEnter?: () => void;
-}
+export type PhoneProps = TextFieldProps;
 export const Phone = ({
   label,
   desc,
@@ -259,24 +217,9 @@ export const Phone = ({
   );
 };
 
-export interface PasswordProps {
-  label?: string;
-  desc?: string;
-  labelClassName?: string;
-  className?: string;
-  value: string | null;
-  onChange: (value: string) => void;
+export interface PasswordProps extends TextFieldProps {
   confirmValue?: string | null;
   onChangeConfirm?: (value: string) => void;
-  inputClassName?: string;
-  placeholder?: string;
-  nullable?: boolean;
-  disabled?: boolean;
-  transform?: (value: string) => string;
-  validate?: (text: string) => boolean | string;
-  minlength?: number;
-  maxlength?: number;
-  onPressEnter?: () => void;
   showConfirm?: boolean;
 }
 export const Password = ({
@@ -316,11 +259,7 @@ export const Password = ({
           disabled={disabled}
           className={cn("w-full", "")}
           inputClassName={cn("w-full focus:border-primary", inputClassName)}
-          validate={(text: string) => {
-            if (text.length < minlength) return l("base.textTooShortError", { minlength });
-            else if (text.length > maxlength) return l("base.textTooLongError", { maxlength });
-            else return validate?.(text) ?? true;
-          }}
+          validate={lengthValidator(l, minlength, maxlength, validate)}
           onPressEnter={onPressEnter}
         />
         {showConfirm ? (

package/ui/Field/index.tsx

@@ -12,16 +12,12 @@ import { Email, Password, Phone, Text, TextArea } from "./Text";
 
 export interface FieldProps {
   className?: string;
-  /** Wrapper around the field controls. */
   containerClassName?: string;
   labelClassName?: string;
-  /** Section label shown above the controls. */
   label?: ReactNode;
-  /** Optional help text shown in the label tooltip. */
   desc?: ReactNode;
   /** Marks the field as optional in the label. */
   nullable?: boolean;
-  /** Field control content. */
   children?: ReactNode;
 }
 const FieldSection = ({
@@ -41,11 +37,6 @@ const FieldSection = ({
   );
 };
 
-/**
- * The form-field namespace. `Object.assign` rather than `Field.X = X` per file, because the members now live
- * beside each other by kind — the assignment form only works where the function and every member are one file,
- * which is how this reached 1600 lines.
- */
 export const Field = Object.assign(FieldSection, {
   Label,
   List,

package/ui/Field/lightRefCache.ts

@@ -0,0 +1,61 @@
+"use client";
+import { fetch, isClientRuntimeRegistered } from "akanjs/client";
+import { capitalize } from "akanjs/common";
+
+interface LightRow {
+  id: string;
+}
+
+export class LightRefCache {
+  static #rows = new Map<string, LightRow | null>();
+  static #inflight = new Map<string, Promise<void>>();
+  static #listeners = new Set<(refName: string, id: string) => void>();
+
+  static get<Light extends LightRow>(refName: string, id: string) {
+    return (LightRefCache.#rows.get(LightRefCache.#keyOf(refName, id)) ?? null) as Light | null;
+  }
+  static subscribe(listener: (refName: string, id: string) => void) {
+    LightRefCache.#listeners.add(listener);
+    return () => {
+      LightRefCache.#listeners.delete(listener);
+    };
+  }
+  static load(refName: string, ids: string[]) {
+    for (const id of ids) LightRefCache.#read(refName, id);
+  }
+  static reset() {
+    LightRefCache.#rows.clear();
+    LightRefCache.#inflight.clear();
+  }
+  static #keyOf(refName: string, id: string) {
+    return `${refName}:${id}`;
+  }
+
+  static #read(refName: string, id: string) {
+    const key = LightRefCache.#keyOf(refName, id);
+    if (LightRefCache.#rows.has(key) || LightRefCache.#inflight.has(key)) return;
+    if (!isClientRuntimeRegistered()) return;
+    const read = (fetch as unknown as { [key: string]: unknown })[`light${capitalize(refName)}`];
+    if (typeof read !== "function") {
+      LightRefCache.#write(refName, id, null);
+      return;
+    }
+    LightRefCache.#inflight.set(
+      key,
+      (read as (id: string) => Promise<LightRow | null>)(id)
+        .then((row) => {
+          LightRefCache.#write(refName, id, row?.id ? row : null);
+        })
+        .catch(() => {
+          LightRefCache.#write(refName, id, null);
+        })
+        .finally(() => {
+          LightRefCache.#inflight.delete(key);
+        }),
+    );
+  }
+  static #write(refName: string, id: string, row: LightRow | null) {
+    LightRefCache.#rows.set(LightRefCache.#keyOf(refName, id), row);
+    for (const listener of LightRefCache.#listeners) listener(refName, id);
+  }
+}