akanjs 3.0.0-alpha.59 → 3.0.0-alpha.60

package/client/clientRuntime.ts

@@ -1,4 +1,5 @@
 import type { SliceMeta } from "akanjs/fetch";
+import type { SerializedArg } from "akanjs/signal";
 import type { ReactNode } from "react";
 import type { TransMessageOption } from "./makePageProto";
 
@@ -49,6 +50,8 @@ type RuntimeFetch = typeof globalThis.fetch & {
   slice: Record<string, SliceMeta>;
   /** Sort keys per model refName, registered from each serialized signal's filter. */
   sortKeyMap?: Map<string, string[]>;
+  /** Filter queries per model refName, with the args each one takes — what the root slice picks from. */
+  filterQueryMap?: Map<string, { [queryKey: string]: SerializedArg[] }>;
   ws: RuntimeWs;
   [key: string]: unknown;
 };

package/client/types.ts

@@ -1,5 +1,5 @@
 import type { BaseInsight } from "akanjs/constant";
-import type { FetchInitForm, SliceMeta } from "akanjs/fetch";
+import type { FetchInitForm, QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { ReactElement, ReactNode } from "react";
 
 export type ReactFontStyle = "normal" | "italic" | "oblique";
@@ -109,7 +109,7 @@ const slugFontPart = (value: string) =>
 export interface ModelsProps<M extends { id: string }> {
   className?: string;
   slice?: SliceMeta;
-  query?: Record<string, unknown>;
+  query?: QuerySetting;
   init?: FetchInitForm<any, any>;
   onClickItem?: (model: M) => unknown;
 }
@@ -127,7 +127,7 @@ export type ModelProps<T extends string, L extends { id: string }> = { [key in T
 export interface ModelDashboardProps<Summary> {
   className?: string;
   summary: Summary;
-  queryMap?: Record<string, unknown>;
+  queryMap?: { [column: string]: QuerySetting };
   columns?: (keyof Summary)[];
   hidePresents?: boolean;
   slice?: SliceMeta;

package/dictionary/dictInfo.ts

@@ -206,12 +206,13 @@ export class ModelDictInfo<
     } as unknown as BaseModelCrudGetSignalTranslation<T, [string, string]>;
   }
   static baseSliceDictionary: {
-    [key in ""]: FunctionTranslation<[string, string], "query">;
+    [key in ""]: FunctionTranslation<[string, string], "queryKey" | "args">;
   } = {
     "": fn(["Universal", "유니버설"])
       .desc(["Universal Slice", "유니버설 슬라이스"])
       .arg((t) => ({
-        query: t(["Query", "쿼리"]).desc(["Query Description", "쿼리 설명"]),
+        queryKey: t(["Query", "쿼리"]).desc(["Filter query to run", "실행할 필터 쿼리"]),
+        args: t(["Arguments", "인자"]).desc(["Arguments of the filter query", "필터 쿼리의 인자"]),
       })),
   };
 

package/document/documentQuery.ts

@@ -157,6 +157,7 @@ export const createDocumentQueryHelper = () => ({
   lte: (value: unknown) => op("lte", value),
   between: (from: unknown, to: unknown) => op("between", [from, to]),
   exists: (path: string) => ({ [path]: op("exists") }),
+
   missing: (path: string) => ({ [path]: op("missing") }),
   empty: (path: string) => ({ [path]: op("empty") }),
   has: (value: unknown) => op("has", value),

package/document/filterMeta.ts

@@ -1,16 +1,18 @@
-import type { Cls, MergeAllDoubleKeyOfObjects, MergeAllKeyOfTypes } from "akanjs/base";
-import { FILTER_DICT_SHAPE, FILTER_META } from "akanjs/base";
-import type {
-  BaseObject,
-  ConstantFieldTypeInput,
-  DocumentModel,
-  FieldToValue,
-  PlainTypeToFieldType,
-  QueryOf,
-  Serialized,
+import type { Cls, EnumInstance, MergeAllDoubleKeyOfObjects, MergeAllKeyOfTypes } from "akanjs/base";
+import { FILTER_DICT_SHAPE, FILTER_META, getNonArrayModel, isEnum } from "akanjs/base";
+import {
+  type BaseObject,
+  type ConstantFieldType,
+  type ConstantFieldTypeInput,
+  type DocumentModel,
+  deserialize,
+  type FieldToValue,
+  type PlainTypeToFieldType,
+  type QueryOf,
+  type Serialized,
 } from "akanjs/constant";
 
-import type { DocumentQuery, DocumentQueryHelper } from "./documentQuery";
+import { type DocumentQuery, type DocumentQueryHelper, documentQueryHelper } from "./documentQuery";
 import type { ConstantFilterMeta } from "./types";
 
 const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
@@ -98,6 +100,70 @@ export const fillMissingFilterArgs = (filterInfo: FilterInfo, args: unknown[]) =
   return [...args, ...Array(filterInfo.args.length - args.length).fill(undefined)];
 };
 
+export interface FilterArgInfo {
+  name: string;
+  argRef: ConstantFieldType;
+  arrDepth: number;
+  enum?: EnumInstance;
+  nullable: boolean;
+  ref?: string;
+}
+/** Unwraps a filter arg's declaration the way `EndpointInfo.getArgInfo` unwraps an endpoint's. */
+export const getFilterArgInfo = (arg: FilterInfo["args"][number]): FilterArgInfo => {
+  const [singleArg, arrDepth] = getNonArrayModel(arg.argRef as Cls);
+  const argIsEnum = isEnum(singleArg);
+  return {
+    name: arg.name,
+    argRef: (argIsEnum ? (singleArg as EnumInstance).type : singleArg) as ConstantFieldType,
+    arrDepth,
+    enum: argIsEnum ? (singleArg as EnumInstance) : undefined,
+    nullable: !!arg.option?.nullable,
+    ref: arg.option?.ref,
+  };
+};
+export const getFilterArgInfos = (filterInfo: FilterInfo): FilterArgInfo[] => filterInfo.args.map(getFilterArgInfo);
+
+/** A caller named a filter that does not exist, or gave it arguments it cannot take. Its callers answer 400. */
+export class FilterQueryError extends Error {}
+
+const tryDeserializeFilterArg = (arg: FilterArgInfo, value: unknown, key: string) => {
+  try {
+    return deserialize(arg.argRef, arg.arrDepth, value, { key: arg.name, nullable: arg.nullable });
+  } catch (error) {
+    throw new FilterQueryError(
+      `Invalid filter argument "${arg.name}" for key: ${key}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+};
+
+/**
+ * Compiles a `(queryKey, args)` pair into the query its filter declares — the root slice's whole contract.
+ * Every arg is parsed by the type the filter declared for it, so a Date arg reaches the query as a Dayjs and
+ * an id that is not one is refused here rather than becoming a query that matches nothing. Args past the
+ * declared ones are dropped: the caller names a filter, never a query.
+ */
+export const resolveFilterQuery = (
+  filterRef: FilterCls,
+  queryKey?: string | null,
+  args?: unknown[] | null,
+): QueryOf<any> => {
+  const key = queryKey || "any";
+  const filterInfo = getFilterMeta(filterRef).query[key];
+  const queryFn = filterInfo?.queryFn;
+  if (!queryFn) throw new FilterQueryError(`No filter query for key: ${key}`);
+  const given = Array.isArray(args) ? args : [];
+  const queryArgs = getFilterArgInfos(filterInfo).map((arg, idx) => {
+    const value = given[idx];
+    if (!arg.nullable && (value === null || value === undefined))
+      throw new FilterQueryError(`Missing filter argument "${arg.name}" for key: ${key}`);
+    const parsed = tryDeserializeFilterArg(arg, value, key);
+
+    return parsed === null ? undefined : parsed;
+  });
+  
+  return queryFn(...queryArgs, documentQueryHelper) as QueryOf<any>;
+};
+
 export const assertFilterFitsCrud = (refName: string, queryKey: string, className: string) => {
   if (queryKey.toLowerCase() !== refName.toLowerCase()) return;
   throw new Error(

package/fetch/client/fetchClient.ts

@@ -81,6 +81,7 @@ export class FetchClient {
   readonly handler: Record<string, FetchHandler>;
   readonly slice: Record<string, SliceMeta> = {};
   readonly sortKeyMap = new Map<string, string[]>();
+  readonly filterQueryMap = new Map<string, { [queryKey: string]: SerializedArg[] }>();
   readonly #originWs = new Map<string, WsClient>();
   readonly #handlerStore: Record<string, FetchHandler> = {};
   readonly #handlerFactory = new Map<string, FetchHandlerFactory>();
@@ -178,10 +179,10 @@ export class FetchClient {
           this.#registerSlice(refName, suffix, slice, signal.prefix);
       }
       if (signal.filter) {
-        this.#registerFilterSortKey(refName, signal.filter.sortKeys);
-        for (const [suffix, args] of Object.entries(signal.filter.filter)) {
-          this.#registerFilterQuery(suffix, args);
-        }
+
+        const filter = this.serializedSignal[refName]?.filter ?? signal.filter;
+        this.#registerFilterSortKey(refName, filter.sortKeys);
+        this.#registerFilterQuery(refName, filter.filter);
       }
     }
     return this;
@@ -279,7 +280,8 @@ export class FetchClient {
   #registerFilterSortKey(refName: string, sortKeys: string[]) {
     this.sortKeyMap.set(refName, sortKeys);
   }
-  #registerFilterQuery(suffix: string, args: SerializedArg[]) {
+  #registerFilterQuery(refName: string, filter: { [queryKey: string]: SerializedArg[] }) {
+    this.filterQueryMap.set(refName, filter);
   }
   #makeHttpFn(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     const argLength = endpoint.args.length;

package/fetch/client/httpClient.ts

@@ -114,7 +114,9 @@ export class HttpClient {
     searchArgs.forEach((arg) => {
       const argValue = argMap.get(arg.name);
       if (argValue === null || argValue === undefined) return;
-      if (arg.arrDepth && Array.isArray(argValue))
+
+      if (arg.refName === "Any") searchParams.set(arg.name, JSON.stringify(argValue));
+      else if (arg.arrDepth && Array.isArray(argValue))
         argValue.forEach((value) => {
           searchParams.append(arg.name, String(value));
         });

package/fetch/fetchType/appliedReturn.type.ts

@@ -8,6 +8,12 @@ export type SliceMeta = {
   argLength: number;
 };
 
+/** What the root slice takes: one of the model's declared filter queries, and the args that filter asks for. */
+export interface QuerySetting {
+  queryKey: string;
+  args?: unknown[];
+}
+
 export type ServerInit<
   RefName extends string,
   Light,

package/package.json

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

package/service/predefinedAdaptor/database.adaptor.ts

@@ -385,6 +385,8 @@ interface SqlDialect {
   docColumn(): string;
   docValuePlaceholder(): string;
   extract(path: string): string;
+  projectExpr(path: string): string;
+  decodeProjected(value: unknown): unknown;
   eq(path: string, value: unknown): SqlFrag;
   ne(path: string, value: unknown): SqlFrag;
   compare(path: string, op: "gt" | "gte" | "lt" | "lte", value: unknown): SqlFrag;
@@ -423,6 +425,13 @@ export class SqliteDialect implements SqlDialect {
   extract(path: string) {
     return `json_extract(${this.docColumn()}, ${this.#path(path)})`;
   }
+
+  projectExpr(path: string) {
+    return `${this.docColumn()} -> ${this.#path(path)}`;
+  }
+  decodeProjected(value: unknown) {
+    return typeof value === "string" ? JSON.parse(value) : value;
+  }
   eq(path: string, value: unknown): SqlFrag {
     return value === null
       ? { sql: `${this.extract(path)} IS NULL`, params: [] }
@@ -554,6 +563,13 @@ export class PostgresDialect implements SqlDialect {
   extract(path: string) {
     return this.#jsonb(path);
   }
+  
+  projectExpr(path: string) {
+    return this.#jsonb(path);
+  }
+  decodeProjected(value: unknown) {
+    return value;
+  }
   eq(path: string, value: unknown): SqlFrag {
     return value === null
       ? { sql: `${this.#jsonb(path)} IS NULL`, params: [] }
@@ -747,6 +763,11 @@ class QueryCompiler {
     return BASE_COLUMNS.has(path) ? quoteIdent(path) : this.dialect.extract(path);
   }
 
+  projectExpr(path: string) {
+    this.assertPath(path);
+    return BASE_COLUMNS.has(path) ? quoteIdent(path) : this.dialect.projectExpr(path);
+  }
+
   private compileNode(query: DocumentQuery, ctx: CompileContext): { sql: string; params: unknown[] } {
     if (this.isQueryNode(query)) {
       if (query.kind === "search") {
@@ -1416,7 +1437,7 @@ export class SqlDocumentStore {
     const jsonFields = fields.filter((field) => !BASE_COLUMNS.has(field));
     const baseColumns = [...BASE_COLUMNS].map((field) => quoteIdent(field));
     const jsonColumns = jsonFields.map(
-      (field, idx) => `${this.compiler.fieldExpr(field)} AS ${quoteIdent(this.projectionAlias(idx))}`,
+      (field, idx) => `${this.compiler.projectExpr(field)} AS ${quoteIdent(this.projectionAlias(idx))}`,
     );
     return [...baseColumns, ...jsonColumns].join(", ");
   }
@@ -1434,7 +1455,7 @@ export class SqlDocumentStore {
     };
     const jsonFields = fields.filter((field) => !BASE_COLUMNS.has(field));
     for (const [idx, field] of jsonFields.entries()) {
-      const value = this.parseProjectedValue(row[this.projectionAlias(idx)]);
+      const value = this.dialect.decodeProjected(row[this.projectionAlias(idx)]);
       const props = (this.database.doc[FIELD_META] as unknown as FieldMap)[field]?.getProps?.();
       if (value === null && !props?.nullable) {
         if (props?.default != null) {
@@ -1514,17 +1535,6 @@ export class SqlDocumentStore {
     );
   }
 
-  private parseProjectedValue(value: unknown) {
-    if (typeof value !== "string") return value;
-    const trimmed = value.trim();
-    if (!trimmed || (trimmed[0] !== "{" && trimmed[0] !== "[")) return value;
-    try {
-      return JSON.parse(trimmed);
-    } catch {
-      return value;
-    }
-  }
-
   private decodeDocumentPayload(payload: Record<string, unknown>) {
     const fields = this.database.doc[FIELD_META] as unknown as FieldMap;
     const result: Record<string, unknown> = {};

package/signal/schema/JsonSchemaBuilder.ts

@@ -38,7 +38,11 @@ export class JsonSchemaBuilder {
   }
 
   arg(arg: SerializedArg): JsonSchema {
-    const schema = arg.enum ? this.#enum(arg.enum) : this.#ref(arg.refName, arg.modelType);
+    const schema = arg.oneOf
+      ? JsonSchemaBuilder.#inlineEnum(arg.oneOf)
+      : arg.enum
+        ? this.#enum(arg.enum)
+        : this.#ref(arg.refName, arg.modelType);
     return JsonSchemaBuilder.#nullable(JsonSchemaBuilder.#arrayed(schema, arg.arrDepth ?? 0), !!arg.nullable);
   }
 

package/signal/serializer/fetch.serializer.ts

@@ -1,7 +1,7 @@
 import { type Cls, ENDPOINT_META, PrimitiveRegistry, type PrimitiveScalar, SLICE_META } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { ConstantRegistry, type ConstantType } from "akanjs/constant";
-import { getFilterMeta } from "akanjs/document";
+import { type FilterArgInfo, getFilterArgInfos, getFilterMeta } from "akanjs/document";
 import type { LiveRegistry } from "akanjs/service";
 import type {
   ArgInfo,
@@ -10,6 +10,7 @@ import type {
   EndpointInfo,
   SerializedArg,
   SerializedEndpoint,
+  SerializedFilter,
   SerializedReturns,
   SerializedSignal,
   SerializedSlice,
@@ -71,6 +72,35 @@ export class FetchSerializer {
     };
   }
 
+  static #serializeFilterArg(argInfo: FilterArgInfo): SerializedArg {
+    const { refName, modelType } = FetchSerializer.#resolveRefInfo(argInfo.argRef as Cls);
+    return {
+      type: "search",
+      refName,
+      name: argInfo.name,
+      ...(modelType ? { modelType: modelType as SerializedArg["modelType"] } : {}),
+      ...(argInfo.arrDepth ? { arrDepth: argInfo.arrDepth } : {}),
+      ...(argInfo.nullable ? { nullable: true } : {}),
+      ...(argInfo.enum ? { enum: argInfo.enum.refName } : {}),
+      ...(argInfo.ref ? { ref: argInfo.ref } : {}),
+    };
+  }
+  /**
+   * The model's filter surface, which is what the root slice takes instead of a raw query. A client cannot
+   * offer a filter it cannot name, nor fill args it cannot type — so both travel, unlike the query map that
+   * used to stay server-side.
+   */
+  static #serializeFilter(sliceCls: SliceCls): SerializedFilter | undefined {
+    const filterMeta = getFilterMeta(sliceCls.srv.db.filter, { allowEmpty: true });
+    if (!filterMeta) return undefined;
+    const filter = Object.fromEntries(
+      Object.entries(filterMeta.query).map(([key, filterInfo]) => [
+        key,
+        getFilterArgInfos(filterInfo).map(FetchSerializer.#serializeFilterArg),
+      ]),
+    );
+    return { filter, sortKeys: Object.keys(filterMeta.sort) };
+  }
   static #serializeSlice(sliceInfo: SliceInfo): SerializedSlice {
     const guards = sliceInfo.signalOption.guards?.map((g) => g.name);
     return {
@@ -92,12 +122,14 @@ export class FetchSerializer {
     for (const [key, endpointInfo] of Object.entries(endpointMeta)) {
       endpoint[key] = FetchSerializer.#serializeEndpoint(endpointInfo);
     }
+    const filter = FetchSerializer.#serializeFilter(sliceCls);
 
-    const sortKeys = Object.keys(getFilterMeta(sliceCls.srv.db.filter, { allowEmpty: true })?.sort ?? {});
+    const queryKeyArg = slice[""]?.args.find((arg) => arg.name === "queryKey");
+    if (queryKeyArg && filter) queryKeyArg.oneOf = Object.keys(filter.filter);
     return {
       ...(prefix ? { prefix } : {}),
       ...(Object.keys(slice).length ? { slice } : {}),
-      ...(sortKeys.length ? { filter: { filter: {}, sortKeys } } : {}),
+      ...(filter ? { filter } : {}),
       ...(sliceCls.getGuards.filter((g) => g.name !== "None").length
         ? { getGuards: sliceCls.getGuards.map((g) => g.name) }
         : {}),

package/signal/signalContext.ts

@@ -1,4 +1,5 @@
 import {
+  Any,
   type BackendEnv,
   type Cls,
   FIELD_META,
@@ -457,6 +458,16 @@ export class HttpExecutionContext<Appended = unknown> {
     if (!this.#url) this.#url = new URL(this.req.url);
     return this.#url;
   }
+  /** The read side of `HttpClient.makeUrl`'s `Any` rule: the query string carries the value JSON-encoded. */
+  static #parseAny(name: string, raw: string | string[] | null): unknown {
+    if (raw === null) return null;
+    if (Array.isArray(raw)) return raw.map((value) => HttpExecutionContext.#parseAny(name, value));
+    try {
+      return JSON.parse(raw);
+    } catch {
+      throw new Exception.BadRequest(`Invalid JSON in "${name}"`);
+    }
+  }
   async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
     if (endpointInfo.args.length === 0) return [];
     this.params = this.req.params;
@@ -496,7 +507,8 @@ export class HttpExecutionContext<Appended = unknown> {
             nullable: arg.option?.nullable,
           });
         case "search": {
-          const value = arg.arrDepth ? this.url.searchParams.getAll(arg.name) : this.url.searchParams.get(arg.name);
+          const raw = arg.arrDepth ? this.url.searchParams.getAll(arg.name) : this.url.searchParams.get(arg.name);
+          const value = arg.argRef === Any ? HttpExecutionContext.#parseAny(arg.name, raw) : raw;
           const result = deserialize(arg.argRef, arg.arrDepth, value, {
             key: arg.name,
             nullable: arg.option?.nullable,

package/signal/slice.ts

@@ -1,8 +1,8 @@
 import { Any, type Assign, type MergeAllKeyOfObjects, SLICE_DICT_SHAPE, SLICE_META } from "akanjs/base";
 import { applyMixins } from "akanjs/common";
-import type { DocumentModel, QueryOf } from "akanjs/constant";
-import type { FilterInstance } from "akanjs/document";
+import { type FilterInstance, FilterQueryError, resolveFilterQuery } from "akanjs/document";
 import { type Adaptor, type AdaptorCls, dangerouslyAdapt, type ServiceModel } from "akanjs/service";
+import { Exception } from "./exception";
 import type { GuardCls } from "./guard";
 import {
   buildSlice,
@@ -52,7 +52,7 @@ interface RootSliceOption {
   prefix?: string;
 }
 
-type RootSliceQuery<SrvModule extends ServiceModel, Full = CnstFull<SrvModule>> = QueryOf<DocumentModel<Full>>;
+type RootSliceQueryKey<Filter extends FilterInstance> = Extract<keyof Filter["query"], string>;
 
 type ExtendSliceInfoObj<
   SrvModule extends ServiceModel,
@@ -91,7 +91,7 @@ export function slice<
   _Light = CnstLight<SrvModule>,
   _Insight = CnstInsight<SrvModule>,
   _Filter extends FilterInstance = DbFilter<SrvModule>,
-  _Query = RootSliceQuery<SrvModule, _Full>,
+  _QueryKey extends string = RootSliceQueryKey<_Filter>,
 >(
   srv: SrvModule,
   option: RootSliceOption,
@@ -111,24 +111,18 @@ export function slice<
             _Insight,
             _Filter,
             SrvMap<SrvModule>,
-            ["query"],
-            [query?: _Query | null],
+            ["queryKey", "args"],
+            [queryKey?: _QueryKey | null, args?: unknown[] | null],
             [],
-            [_Query]
+            [_QueryKey | undefined, unknown[] | undefined]
           >;
         }
       : ExtendSliceInfoObj<SrvModule, LibSlices>
   >
 > {
   if (!srv.cnst || !srv.db) throw new Error("cnst and db are required");
-  const init = buildSlice(
-    srv.srv.refName,
-    srv.cnst.input,
-    srv.cnst.full,
-    srv.cnst.light,
-    srv.cnst.insight,
-    srv.db.filter,
-  );
+  const filterRef = srv.db.filter;
+  const init = buildSlice(srv.srv.refName, srv.cnst.input, srv.cnst.full, srv.cnst.light, srv.cnst.insight, filterRef);
   const toGuards = (guard?: GuardCls | GuardCls[]) => (guard ? (Array.isArray(guard) ? guard : [guard]) : []);
   const rootGuards = toGuards(option.guards?.root);
   const getGuards = toGuards(option.guards?.get);
@@ -152,9 +146,19 @@ export function slice<
     static removeGuards = removeGuards;
     static [SLICE_META] = Object.assign(
       {
+
         [""]: init({ guards: rootGuards })
-          .search<"query", object>("query", Any)
-          .exec((query) => query ?? {}),
+          .search<"queryKey", string>("queryKey", String)
+          .search<"args", unknown[]>("args", Any)
+          .exec((queryKey, args) => {
+            try {
+              return resolveFilterQuery(filterRef, queryKey, args);
+            } catch (error) {
+
+              if (error instanceof FilterQueryError) throw new Exception.BadRequest(error.message);
+              throw error;
+            }
+          }),
       },
       sliceBuilder(init as Parameters<BuildSlice>[0]),
     );

package/signal/types.ts

@@ -120,12 +120,17 @@ export interface SerializedArg {
   nullable?: boolean;
   example?: string | number | boolean | Date;
   enum?: string;
+  /** The values this arg accepts, when they are a fixed list the caller has to pick from. */
+  oneOf?: (string | number)[];
+  /** For an id a filter declared against a model: the model it points at, so a UI can offer a picker. */
+  ref?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
   type: "query" | "mutation" | "pubsub" | "message" | "prompt";
   returns: SerializedReturns;
 }
 export interface SerializedFilter {
+  /** Every filter query the model declares, by key, with the args each one takes. */
   filter: { [key: string]: SerializedArg[] };
   sortKeys: string[];
 }

package/types/client/clientRuntime.d.ts

@@ -1,4 +1,5 @@
 import type { SliceMeta } from "akanjs/fetch";
+import type { SerializedArg } from "akanjs/signal";
 import type { ReactNode } from "react";
 import type { TransMessageOption } from "./makePageProto.d.ts";
 type RuntimeTranslate = ((key: string, param?: Record<string, string | number>) => string) & {
@@ -41,6 +42,10 @@ type RuntimeFetch = typeof globalThis.fetch & {
     slice: Record<string, SliceMeta>;
     /** Sort keys per model refName, registered from each serialized signal's filter. */
     sortKeyMap?: Map<string, string[]>;
+    /** Filter queries per model refName, with the args each one takes — what the root slice picks from. */
+    filterQueryMap?: Map<string, {
+        [queryKey: string]: SerializedArg[];
+    }>;
     ws: RuntimeWs;
     [key: string]: unknown;
 };

package/types/client/types.d.ts

@@ -1,5 +1,5 @@
 import type { BaseInsight } from "akanjs/constant";
-import type { FetchInitForm, SliceMeta } from "akanjs/fetch";
+import type { FetchInitForm, QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { ReactElement, ReactNode } from "react";
 export type ReactFontStyle = "normal" | "italic" | "oblique";
 export type ReactFontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
@@ -37,7 +37,7 @@ export interface ModelsProps<M extends {
 }> {
     className?: string;
     slice?: SliceMeta;
-    query?: Record<string, unknown>;
+    query?: QuerySetting;
     init?: FetchInitForm<any, any>;
     onClickItem?: (model: M) => unknown;
 }
@@ -57,7 +57,9 @@ export type ModelProps<T extends string, L extends {
 export interface ModelDashboardProps<Summary> {
     className?: string;
     summary: Summary;
-    queryMap?: Record<string, unknown>;
+    queryMap?: {
+        [column: string]: QuerySetting;
+    };
     columns?: (keyof Summary)[];
     hidePresents?: boolean;
     slice?: SliceMeta;

package/types/dictionary/dictInfo.d.ts

@@ -73,7 +73,7 @@ export declare class ModelDictInfo<Languages extends [string, ...string[]] = [st
     };
     static getBaseSignalDictionary<T extends string>(refName: T): BaseModelCrudGetSignalTranslation<T, [string, string]>;
     static baseSliceDictionary: {
-        [key in ""]: FunctionTranslation<[string, string], "query">;
+        [key in ""]: FunctionTranslation<[string, string], "queryKey" | "args">;
     };
     languages: Languages;
     modelTranslation?: FieldTranslation<Languages>;

package/types/document/filterMeta.d.ts

@@ -1,7 +1,7 @@
-import type { Cls, MergeAllDoubleKeyOfObjects, MergeAllKeyOfTypes } from "akanjs/base";
+import type { Cls, EnumInstance, MergeAllDoubleKeyOfObjects, MergeAllKeyOfTypes } from "akanjs/base";
 import { FILTER_DICT_SHAPE, FILTER_META } from "akanjs/base";
-import type { BaseObject, ConstantFieldTypeInput, DocumentModel, FieldToValue, PlainTypeToFieldType, QueryOf, Serialized } from "akanjs/constant";
-import type { DocumentQuery, DocumentQueryHelper } from "./documentQuery.d.ts";
+import { type BaseObject, type ConstantFieldType, type ConstantFieldTypeInput, type DocumentModel, type FieldToValue, type PlainTypeToFieldType, type QueryOf, type Serialized } from "akanjs/constant";
+import { type DocumentQuery, type DocumentQueryHelper } from "./documentQuery.d.ts";
 import type { ConstantFilterMeta } from "./types.d.ts";
 export declare const isFilterModel: (filterRef: Cls<unknown, {
     [FILTER_META]?: ConstantFilterMeta;
@@ -19,6 +19,27 @@ export declare const getFilterInfoByKey: <ArgNames extends string[] = [], Args e
 export declare const setFilterInfoByKey: <ArgNames extends string[] = [], Args extends any[] = any[], Model = any>(modelRef: Cls<Model>, key: string, filterInfo: FilterInfo<ArgNames, Args, Model>) => void;
 export declare const getFilterSortByKey: (modelRef: FilterCls, key: string) => unknown;
 export declare const fillMissingFilterArgs: (filterInfo: FilterInfo, args: unknown[]) => any[];
+export interface FilterArgInfo {
+    name: string;
+    argRef: ConstantFieldType;
+    arrDepth: number;
+    enum?: EnumInstance;
+    nullable: boolean;
+    ref?: string;
+}
+/** Unwraps a filter arg's declaration the way `EndpointInfo.getArgInfo` unwraps an endpoint's. */
+export declare const getFilterArgInfo: (arg: FilterInfo["args"][number]) => FilterArgInfo;
+export declare const getFilterArgInfos: (filterInfo: FilterInfo) => FilterArgInfo[];
+/** A caller named a filter that does not exist, or gave it arguments it cannot take. Its callers answer 400. */
+export declare class FilterQueryError extends Error {
+}
+/**
+ * Compiles a `(queryKey, args)` pair into the query its filter declares — the root slice's whole contract.
+ * Every arg is parsed by the type the filter declared for it, so a Date arg reaches the query as a Dayjs and
+ * an id that is not one is refused here rather than becoming a query that matches nothing. Args past the
+ * declared ones are dropped: the caller names a filter, never a query.
+ */
+export declare const resolveFilterQuery: (filterRef: FilterCls, queryKey?: string | null, args?: unknown[] | null) => QueryOf<any>;
 export declare const assertFilterFitsCrud: (refName: string, queryKey: string, className: string) => void;
 export type BaseFilterSortKey = "latest" | "oldest" | "relevance";
 export type BaseFilterQueryKey = "any";

package/types/fetch/client/fetchClient.d.ts

@@ -27,6 +27,9 @@ export declare class FetchClient {
     readonly handler: Record<string, FetchHandler>;
     readonly slice: Record<string, SliceMeta>;
     readonly sortKeyMap: Map<string, string[]>;
+    readonly filterQueryMap: Map<string, {
+        [queryKey: string]: SerializedArg[];
+    }>;
     serializedSignal: {
         [key: string]: SerializedSignal;
     };

package/types/fetch/fetchType/appliedReturn.type.d.ts

@@ -6,6 +6,11 @@ export type SliceMeta = {
     sliceName: string;
     argLength: number;
 };
+/** What the root slice takes: one of the model's declared filter queries, and the args that filter asks for. */
+export interface QuerySetting {
+    queryKey: string;
+    args?: unknown[];
+}
 export type ServerInit<RefName extends string, Light, Insight = any, QueryArgs = any, Filter extends FilterInstance = any, _CapitalizedRefName extends string = Capitalize<RefName>, _LightObj = GetStateObject<Light>, _InsightObj = GetStateObject<Insight>, _Sort = ExtractSort<Filter>> = SliceMeta & {
     [K in `${RefName}ObjList`]: _LightObj[];
 } & {

package/types/service/predefinedAdaptor/database.adaptor.d.ts

@@ -201,6 +201,8 @@ interface SqlDialect {
     docColumn(): string;
     docValuePlaceholder(): string;
     extract(path: string): string;
+    projectExpr(path: string): string;
+    decodeProjected(value: unknown): unknown;
     eq(path: string, value: unknown): SqlFrag;
     ne(path: string, value: unknown): SqlFrag;
     compare(path: string, op: "gt" | "gte" | "lt" | "lte", value: unknown): SqlFrag;
@@ -224,6 +226,8 @@ export declare class SqliteDialect implements SqlDialect {
     docColumn(): string;
     docValuePlaceholder(): string;
     extract(path: string): string;
+    projectExpr(path: string): string;
+    decodeProjected(value: unknown): any;
     eq(path: string, value: unknown): SqlFrag;
     ne(path: string, value: unknown): SqlFrag;
     compare(path: string, op: "gt" | "gte" | "lt" | "lte", value: unknown): SqlFrag;
@@ -247,6 +251,8 @@ export declare class PostgresDialect implements SqlDialect {
     docColumn(): string;
     docValuePlaceholder(): string;
     extract(path: string): string;
+    projectExpr(path: string): string;
+    decodeProjected(value: unknown): unknown;
     eq(path: string, value: unknown): SqlFrag;
     ne(path: string, value: unknown): SqlFrag;
     compare(path: string, op: "gt" | "gte" | "lt" | "lte", value: unknown): SqlFrag;
@@ -272,6 +278,7 @@ declare class QueryCompiler {
     compile(query?: DocumentQuery): CompiledQuery;
     orderBy(sort?: Record<string, 1 | -1>): string;
     fieldExpr(path: string): string;
+    projectExpr(path: string): string;
     private compileNode;
     private compileField;
     private assertPath;
@@ -379,7 +386,6 @@ export declare class SqlDocumentStore {
     private findOneForWrite;
     private pickByIdForWrite;
     private writeUpdatedDocument;
-    private parseProjectedValue;
     private decodeDocumentPayload;
     private decodeFieldValue;
     private decodeMapValue;

package/types/signal/slice.d.ts

@@ -1,6 +1,5 @@
 import { type Assign, type MergeAllKeyOfObjects, SLICE_DICT_SHAPE, SLICE_META } from "akanjs/base";
-import type { DocumentModel, QueryOf } from "akanjs/constant";
-import type { FilterInstance } from "akanjs/document";
+import { type FilterInstance } from "akanjs/document";
 import { type Adaptor, type AdaptorCls, type ServiceModel } from "akanjs/service";
 import type { GuardCls } from "./guard.d.ts";
 import { type SliceBuilder, type SliceInfo, type SliceInfoArgNames, type SliceInfoArgs, type SliceInfoInternalArgs, type SliceInfoServerArgs, type SliceInfoSrvs } from "./sliceInfo.d.ts";
@@ -42,19 +41,22 @@ interface RootSliceOption {
     };
     prefix?: string;
 }
-type RootSliceQuery<SrvModule extends ServiceModel, Full = CnstFull<SrvModule>> = QueryOf<DocumentModel<Full>>;
+type RootSliceQueryKey<Filter extends FilterInstance> = Extract<keyof Filter["query"], string>;
 type ExtendSliceInfoObj<SrvModule extends ServiceModel, LibSlices extends SliceCls[], _Input = CnstInput<SrvModule>, _Full = CnstFull<SrvModule>, _Light = CnstLight<SrvModule>, _Insight = CnstInsight<SrvModule>, _Filter extends FilterInstance = DbFilter<SrvModule>, _Merged = MergeAllKeyOfObjects<LibSlices, typeof SLICE_META>> = {
     [K in keyof _Merged]: _Merged[K] extends SliceInfo ? SliceInfo<SrvRefName<SrvModule>, _Input, _Full, _Light, _Insight, _Filter, SliceInfoSrvs<_Merged[K]>, SliceInfoArgNames<_Merged[K]>, SliceInfoArgs<_Merged[K]>, SliceInfoInternalArgs<_Merged[K]>, SliceInfoServerArgs<_Merged[K]>> : never;
 };
 /** Builds database-backed slice APIs for list, insight, init, view, edit, create, update, and remove flows. */
-export declare function slice<SrvModule extends ServiceModel, BuildSlice extends SliceBuilder<SrvModule>, LibSlices extends SliceCls[], _Input = CnstInput<SrvModule>, _Full = CnstFull<SrvModule>, _Light = CnstLight<SrvModule>, _Insight = CnstInsight<SrvModule>, _Filter extends FilterInstance = DbFilter<SrvModule>, _Query = RootSliceQuery<SrvModule, _Full>>(srv: SrvModule, option: RootSliceOption, sliceBuilder: BuildSlice, ...libSlices: LibSlices): SliceCls<SrvModule, Assign<ReturnType<BuildSlice>, LibSlices extends [] ? {
+export declare function slice<SrvModule extends ServiceModel, BuildSlice extends SliceBuilder<SrvModule>, LibSlices extends SliceCls[], _Input = CnstInput<SrvModule>, _Full = CnstFull<SrvModule>, _Light = CnstLight<SrvModule>, _Insight = CnstInsight<SrvModule>, _Filter extends FilterInstance = DbFilter<SrvModule>, _QueryKey extends string = RootSliceQueryKey<_Filter>>(srv: SrvModule, option: RootSliceOption, sliceBuilder: BuildSlice, ...libSlices: LibSlices): SliceCls<SrvModule, Assign<ReturnType<BuildSlice>, LibSlices extends [] ? {
     [""]: SliceInfo<SrvRefName<SrvModule>, _Input, _Full, _Light, _Insight, _Filter, SrvMap<SrvModule>, [
-        "query"
+        "queryKey",
+        "args"
     ], [
-        query?: _Query | null
+        queryKey?: _QueryKey | null,
+        args?: unknown[] | null
     ], [
     ], [
-        _Query
+        _QueryKey | undefined,
+        unknown[] | undefined
     ]>;
 } : ExtendSliceInfoObj<SrvModule, LibSlices>>>;
 export {};

package/types/signal/types.d.ts

@@ -107,12 +107,17 @@ export interface SerializedArg {
     nullable?: boolean;
     example?: string | number | boolean | Date;
     enum?: string;
+    /** The values this arg accepts, when they are a fixed list the caller has to pick from. */
+    oneOf?: (string | number)[];
+    /** For an id a filter declared against a model: the model it points at, so a UI can offer a picker. */
+    ref?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
     type: "query" | "mutation" | "pubsub" | "message" | "prompt";
     returns: SerializedReturns;
 }
 export interface SerializedFilter {
+    /** Every filter query the model declares, by key, with the args each one takes. */
     filter: {
         [key: string]: SerializedArg[];
     };

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

@@ -1,10 +1,12 @@
-import type { SliceMeta } from "akanjs/fetch";
+import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 export interface DashboardProps<T extends string, State> {
     className?: string;
     summary: Record<string, unknown>;
     slice: SliceMeta;
     /** Columns that narrow the listing when clicked. A column absent from the map renders as a plain tile. */
-    queryMap?: Record<string, unknown>;
+    queryMap?: {
+        [column: string]: QuerySetting;
+    };
     columns?: string[];
     presents?: string[];
     hidePresents?: boolean;

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

@@ -1,5 +1,5 @@
 import { type DataAction, type DataColumn, type DataTool, type ModelInsightProps, type ModelProps } from "akanjs/client";
-import type { FetchInitForm, SliceMeta } from "akanjs/fetch";
+import type { FetchInitForm, QuerySetting, SliceMeta } from "akanjs/fetch";
 import { type ReactNode } from "react";
 export interface ListContainerProps<T extends string, State, Input, Full extends {
     id: string;
@@ -12,8 +12,12 @@ export interface ListContainerProps<T extends string, State, Input, Full extends
     cardListClassName?: string;
     /** Initial rendering mode. The toolbar toggle switches it from here. */
     type?: "card" | "list";
-    /** Static query object passed as the first argument of the generated init action. */
-    query?: Record<string, unknown>;
+    /** Fixed filter query for this listing. Given one, the panel is scoped and offers no query maker. */
+    query?: QuerySetting;
+    /** Summary column to filter query. A `?filter=<column>` link opens the listing on the query it names. */
+    queryMap?: {
+        [column: string]: QuerySetting;
+    };
     /** Initial fetch form: page, limit, sort, and the default values a new model starts from. */
     init?: FetchInitForm<Input, any>;
     /** Generated slice metadata for the target model. */
@@ -46,4 +50,4 @@ export default function ListContainer<T extends string, State, Input, Full exten
     id: string;
 }, Light extends {
     id: string;
-}>({ className, cardListClassName, type, query, init, create, slice, title, sort, columns, actions, tools, renderDashboard, renderItem, renderTemplate, renderTitle, renderView, renderQueryMaker, renderInsight, renderLoading, }: ListContainerProps<T, State, Input, Full, Light>): import("react/jsx-runtime").JSX.Element;
+}>({ className, cardListClassName, type, query, queryMap, init, create, slice, title, sort, columns, actions, tools, renderDashboard, renderItem, renderTemplate, renderTitle, renderView, renderQueryMaker, renderInsight, renderLoading, }: ListContainerProps<T, State, Input, Full, Light>): import("react/jsx-runtime").JSX.Element;

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

@@ -1,8 +1,8 @@
-import type { SliceMeta } from "akanjs/fetch";
+import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 interface QueryMakerProps {
     className?: string;
     slice: SliceMeta;
-    query?: Record<string, unknown>;
+    query?: QuerySetting;
 }
-export default function QueryMaker({ className, slice, query }: QueryMakerProps): null;
+export default function QueryMaker({ className, slice, query }: QueryMakerProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

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

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

package/types/ui/Model/AdminPanel.d.ts

@@ -1,4 +1,4 @@
-import type { SliceMeta } from "akanjs/fetch";
+import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { ListContainerProps } from "../Data/ListContainer.d.ts";
 interface AdminPanelProps<T extends string, State, Input, Full extends {
     id: string;
@@ -21,9 +21,9 @@ interface AdminPanelProps<T extends string, State, Input, Full extends {
     template?: any;
     unit?: any;
     view?: any;
-    /** Summary column to query descriptor. Only a column this map names becomes a link to its filtered listing. */
+    /** Summary column to filter query. Only a column this map names becomes a link to its filtered listing. */
     queryMap?: {
-        [key: string]: unknown;
+        [column: string]: QuerySetting;
     };
     /** Keys of the app's `summary` state shown as dashboard tiles above the list. */
     summaryColumns?: string[];

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

@@ -9,7 +9,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, value, onChange }: ArgQueryProps) => import("react/jsx-runtime").JSX.Element;
+    var Query: ({ endpointKey, arg, label, value, onChange }: 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;
@@ -35,6 +35,7 @@ interface ArgParamProps {
 interface ArgQueryProps {
     endpointKey: string;
     arg: SerializedArg;
+    label?: string;
     value: any;
     onChange: (value: any) => void;
 }
@@ -45,7 +46,7 @@ interface ArgFormDataProps {
     onChange: (value: any) => void;
 }
 interface ArgIDProps {
-    value: string;
+    value: string | null;
     onChange: (value: string) => void;
 }
 interface ArgIntProps {
@@ -57,7 +58,7 @@ interface ArgFloatProps {
     onChange: (value: number) => void;
 }
 interface ArgStringProps {
-    value: string;
+    value: string | null;
     onChange: (value: string) => void;
 }
 interface ArgBooleanProps {

package/ui/Data/Dashboard.tsx

@@ -1,6 +1,6 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
-import type { SliceMeta } from "akanjs/fetch";
+import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 import { st } from "akanjs/store";
 
 import { Link } from "../Link";
@@ -11,7 +11,7 @@ export interface DashboardProps<T extends string, State> {
   summary: Record<string, unknown>;
   slice: SliceMeta;
   /** Columns that narrow the listing when clicked. A column absent from the map renders as a plain tile. */
-  queryMap?: Record<string, unknown>;
+  queryMap?: { [column: string]: QuerySetting };
   columns?: string[];
   presents?: string[];
   hidePresents?: boolean;

package/ui/Data/ListContainer.tsx

@@ -12,7 +12,7 @@ import {
 } from "akanjs/client";
 import { capitalize } from "akanjs/common";
 import { type BaseInsight, ConstantRegistry, labelOf } from "akanjs/constant";
-import type { FetchInitForm, SliceMeta } from "akanjs/fetch";
+import type { FetchInitForm, QuerySetting, SliceMeta } from "akanjs/fetch";
 import { st } from "akanjs/store";
 import { useScreenScope } from "akanjs/webkit";
 import { type ReactNode, useEffect, useState } from "react";
@@ -36,6 +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 DataTableList from "./TableList";
 
 const controlClassName = "h-9";
@@ -55,8 +56,10 @@ export interface ListContainerProps<
   cardListClassName?: string;
   /** Initial rendering mode. The toolbar toggle switches it from here. */
   type?: "card" | "list";
-  /** Static query object passed as the first argument of the generated init action. */
-  query?: Record<string, unknown>;
+  /** Fixed filter query for this listing. Given one, the panel is scoped and offers no query maker. */
+  query?: QuerySetting;
+  /** Summary column to filter query. A `?filter=<column>` link opens the listing on the query it names. */
+  queryMap?: { [column: string]: QuerySetting };
   /** Initial fetch form: page, limit, sort, and the default values a new model starts from. */
   init?: FetchInitForm<Input, any>;
   /** Generated slice metadata for the target model. */
@@ -100,6 +103,7 @@ export default function ListContainer<
   cardListClassName,
   type = "card",
   query,
+  queryMap,
   init,
   create = true,
   slice,
@@ -167,10 +171,13 @@ export default function ListContainer<
   const sortOfModel = storeUse[namesOfSlice.sortOfModel]() as string;
   const modelInsight = storeUse[namesOfSlice.modelInsight]() as BaseInsight;
   const modelListLoading = storeUse[namesOfSlice.modelListLoading]() as string | boolean;
+  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);
   useEffect(() => {
     
     const queryArgs = new Array(slice.argLength).fill(null) as unknown[];
-    if (query) queryArgs[0] = query;
+    if (initQuery) [queryArgs[0], queryArgs[1]] = [initQuery.queryKey, initQuery.args ?? []];
     void storeDo[namesOfSlice.initModel](...queryArgs, { sort, ...init });
   }, []);
 
@@ -254,7 +261,9 @@ export default function ListContainer<
     if (!Stat || !summary) return null;
     return summaryLoading ? <Loading.Skeleton className="mb-4" active /> : <Stat summary={summary} hidePresents />;
   };
-  const RenderQueryMaker = renderQueryMaker;
+  
+  const RenderQueryMaker =
+    renderQueryMaker ?? (query ? undefined : () => <DataQueryMaker slice={slice} query={initQuery} />);
   const RenderInsight = (): ReactNode => (renderInsight ? renderInsight({ insight: modelInsight }) : null);
   const RenderTemplate = renderTemplate;
   const RenderTools = (): ReactNode => {

package/ui/Data/QueryMaker.tsx

@@ -1,21 +1,71 @@
 "use client";
-
-import type { SliceMeta } from "akanjs/fetch";
+import { cn, fetch, usePage } from "akanjs/client";
+import { capitalize } from "akanjs/common";
+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 { Select } from "../Select";
+import Arg from "../Signal/Arg";
+import { dictLabel } from "./dataText";
 
 interface QueryMakerProps {
   className?: string;
   slice: SliceMeta;
-  query?: Record<string, unknown>;
-}
-interface QuerySetting {
-  queryKey: string;
-  arg: Record<string, unknown>;
+  query?: QuerySetting;
 }
-const searchQuerySetting: QuerySetting = { queryKey: "search", arg: { $search: undefined as string | undefined } };
-const byStatusQuerySetting: QuerySetting = { queryKey: "byStatuses", arg: { statuses: null } };
+
+const isFillableArg = (arg: SerializedArg) => !arg.modelType;
+const defaultArg = (arg: SerializedArg) => ((arg.arrDepth ?? 0) > 0 ? [] : null);
 
 export default function QueryMaker({ className, slice, query }: QueryMakerProps) {
-  const { sliceName } = slice;
-  return null;
+  const { l } = usePage();
+  const { refName, sliceName } = slice;
+  const storeDo = st.do as unknown as { [key: string]: (...args: unknown[]) => Promise<void> };
+  const filterQuery = fetch.filterQueryMap?.get(refName) ?? {};
+  const queryKeys = Object.entries(filterQuery)
+    .filter(([, args]) => args.every(isFillableArg))
+    .map(([queryKey]) => queryKey);
+  const [setting, setSetting] = useState<Required<QuerySetting>>({
+    queryKey: query?.queryKey ?? queryKeys[0] ?? "any",
+    args: query?.args ?? [],
+  });
+  
+  const applyQuery = useDebounce((setting: Required<QuerySetting>) => {
+    void storeDo[`setQueryArgsOf${capitalize(sliceName)}`](setting.queryKey, setting.args);
+  }, []);
+  const update = (setting: Required<QuerySetting>) => {
+    setSetting(setting);
+    applyQuery(setting);
+  };
+  const args = filterQuery[setting.queryKey] ?? [];
+  if (queryKeys.length < 2) 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)))) });
+          }}
+        />
+      ))}
+    </div>
+  );
 }
-

package/ui/Data/index.ts

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

package/ui/Model/AdminPanel.tsx

@@ -1,6 +1,6 @@
 import type { ModelProps } from "akanjs/client";
 import type { BaseInsight } from "akanjs/constant";
-import type { SliceMeta } from "akanjs/fetch";
+import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 import type { ComponentType, ReactNode } from "react";
 import { Data } from "../Data";
 import type { ListContainerProps } from "../Data/ListContainer";
@@ -17,8 +17,8 @@ interface AdminPanelProps<T extends string, State, Input, Full extends { id: str
   template?: any;
   unit?: any;
   view?: any;
-  /** Summary column to query descriptor. Only a column this map names becomes a link to its filtered listing. */
-  queryMap?: { [key: string]: unknown };
+  /** Summary column to filter query. Only a column this map names becomes a link to its filtered listing. */
+  queryMap?: { [column: string]: QuerySetting };
   /** Keys of the app's `summary` state shown as dashboard tiles above the list. */
   summaryColumns?: string[];
   /** Model insight keys shown above the list. The header already carries the total count. */
@@ -70,6 +70,7 @@ export default function AdminPanel<
   return (
     <Data.ListContainer
       slice={slice}
+      queryMap={queryMap}
       renderItem={Unit}
       renderInsight={renderInsight}
       renderDashboard={renderDashboard}

package/ui/Signal/Arg.tsx

@@ -10,6 +10,7 @@ import { buttonRecipe } from "../Button";
 import { DatePicker } from "../DatePicker";
 import { Input } from "../Input";
 import { dictText, docDash, docUi } from "../Reference";
+import { Select } from "../Select";
 import { Tooltip } from "../Tooltip";
 import UiObject from "./Object";
 import { signalUi } from "./style";
@@ -137,20 +138,32 @@ Arg.Param = ArgParam;
 interface ArgQueryProps {
   endpointKey: string;
   arg: SerializedArg;
+  label?: string;
   value: any;
   onChange: (value: any) => void;
 }
-const ArgQuery = ({ endpointKey, arg, value, onChange }: ArgQueryProps) => {
+const ArgQuery = ({ endpointKey, arg, label, value, onChange }: 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)
     throw new Error(`Query arg - ${endpointKey}/${arg.name} must not be more than 2D array`);
   const argType = PrimitiveRegistry.getName(argRef as typeof PrimitiveScalar) as DefaultPrimitiveName;
+  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;
   return (
     <div className={signalUi.inputRow}>
-      <div className={signalUi.inputLabel}>{arg.name}</div>
+      <div className={signalUi.inputLabel}>{label ?? arg.name}</div>
       <div className="w-full">
-        {(arg.arrDepth ?? 0) > 0 && Array.isArray(value) ? (
+        {options.length ? (
+          <Select<string | number, boolean>
+            options={options.map((option) => ({ label: option, value: option }))}
+            multiple={multiple}
+            nullable={arg.nullable}
+            value={multiple ? ((value as (string | number)[] | null) ?? []) : (value as string | number)}
+            onChange={onChange}
+          />
+        ) : multiple && Array.isArray(value) ? (
           <div className="flex flex-col gap-2">
             {value.map((val, idx) => (
               <div className="flex items-center gap-2" key={idx}>
@@ -214,14 +227,14 @@ const ArgFormData = ({ endpointKey, arg, value, onChange }: ArgFormDataProps) =>
 Arg.FormData = ArgFormData;
 
 interface ArgIDProps {
-  value: string;
+  value: string | null;
   onChange: (value: string) => void;
 }
 const ArgID = ({ value, onChange }: ArgIDProps) => {
   return (
     <Input
       inputClassName="w-full font-mono"
-      value={value}
+      value={value ?? ""}
       onChange={(value) => {
         onChange(value);
       }}
@@ -268,14 +281,14 @@ const ArgFloat = ({ value, onChange }: ArgFloatProps) => {
 Arg.Float = ArgFloat;
 
 interface ArgStringProps {
-  value: string;
+  value: string | null;
   onChange: (value: string) => void;
 }
 const ArgString = ({ value, onChange }: ArgStringProps) => {
   return (
     <Input
       inputClassName="w-full font-mono"
-      value={value}
+      value={value ?? ""}
       onChange={(value) => {
         onChange(value);
       }}

package/ui/Signal/makeExample.ts

@@ -44,7 +44,7 @@ const getRequestExample = (modelRef: Cls) => {
       else
         example[key] = (
           (field.example ?? field.enum)
-            ? arraiedModel(field.example ?? (field.enum?.values as string[])[0], field.optArrDepth)
+            ? arraiedModel(field.example ?? field.enum?.values[0], field.optArrDepth)
             : arraiedModel(getRequestExample(field.modelRef), field.arrDepth)
         ) as unknown;
     });