akanjs 3.0.0-alpha.62 → 3.0.0-alpha.63

package/constant/fieldQueryMeta.ts

@@ -0,0 +1,35 @@
+import { FIELD_META } from "akanjs/base";
+import { ConstantRegistry } from "./constantRegistry";
+import type { FieldObject } from "./fieldInfo";
+
+/**
+ * The query a field's value stands for, declared on the field itself with `.meta(...)`. A summary counter is the
+ * case this exists for: `hau` is however many rows one filter returns, so the tile showing it can open that exact
+ * listing without the page restating the filter beside it.
+ *
+ * The shape is read structurally rather than by class, so an app declares it with whatever builder it already has.
+ */
+export interface FieldQueryMeta {
+  /** The model the query runs against. */
+  refName: string;
+  /** One of that model's declared filter keys. */
+  queryKey: string | null;
+  /** Read when the query is applied, so an arg relative to now — `() => [dayjs().subtract(1, "hour")]` — is current. */
+  queryArgs?: unknown[] | (() => unknown[]);
+}
+
+const isFieldQueryMeta = (meta: unknown): meta is FieldQueryMeta => {
+  if (!meta || typeof meta !== "object") return false;
+  const { refName, queryKey, queryArgs } = meta as Record<string, unknown>;
+  if (typeof refName !== "string" || !refName) return false;
+  if (queryKey !== null && typeof queryKey !== "string") return false;
+  return queryArgs === undefined || Array.isArray(queryArgs) || typeof queryArgs === "function";
+};
+
+/** The query one field of `refName` names, or nothing when the model, the field, or the declaration is absent. */
+export const fieldQueryMetaOf = (refName: string, field: string): FieldQueryMeta | undefined => {
+  const cnst = ConstantRegistry.getDatabase(refName, { allowEmpty: true });
+  const fieldMap = cnst?.full[FIELD_META] as FieldObject | undefined;
+  const meta = fieldMap?.[field]?.meta;
+  return isFieldQueryMeta(meta) ? meta : undefined;
+};

package/constant/index.ts

@@ -3,6 +3,7 @@ export * from "./constantRegistry";
 export * from "./crystalize";
 export * from "./deserialize";
 export * from "./fieldInfo";
+export * from "./fieldQueryMeta";
 export * from "./getDefault";
 export * from "./immerify";
 export * from "./labelOf";

package/package.json

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

package/types/constant/fieldQueryMeta.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The query a field's value stands for, declared on the field itself with `.meta(...)`. A summary counter is the
+ * case this exists for: `hau` is however many rows one filter returns, so the tile showing it can open that exact
+ * listing without the page restating the filter beside it.
+ *
+ * The shape is read structurally rather than by class, so an app declares it with whatever builder it already has.
+ */
+export interface FieldQueryMeta {
+    /** The model the query runs against. */
+    refName: string;
+    /** One of that model's declared filter keys. */
+    queryKey: string | null;
+    /** Read when the query is applied, so an arg relative to now — `() => [dayjs().subtract(1, "hour")]` — is current. */
+    queryArgs?: unknown[] | (() => unknown[]);
+}
+/** The query one field of `refName` names, or nothing when the model, the field, or the declaration is absent. */
+export declare const fieldQueryMetaOf: (refName: string, field: string) => FieldQueryMeta | undefined;

package/types/constant/index.d.ts

@@ -3,6 +3,7 @@ export * from "./constantRegistry.d.ts";
 export * from "./crystalize.d.ts";
 export * from "./deserialize.d.ts";
 export * from "./fieldInfo.d.ts";
+export * from "./fieldQueryMeta.d.ts";
 export * from "./getDefault.d.ts";
 export * from "./immerify.d.ts";
 export * from "./labelOf.d.ts";

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

@@ -4,10 +4,15 @@ export interface DashboardProps<T extends string, State> {
     summary: Record<string, unknown>;
     /** The listing these tiles belong to. Kept so a caller names its target; the labels are app-level keys. */
     slice: SliceMeta;
-    /** Columns that narrow the listing when clicked. A column absent from the map renders as a plain tile. */
+    /**
+     * Overrides the filter a column applies. A column left out still narrows the listing when its own field
+     * declares a query with `.meta(...)`; one with neither renders as a plain tile.
+     */
     queryMap?: {
         [column: string]: QuerySetting;
     };
+    /** Model whose fields the columns name. Its `.meta(...)` declarations are where a tile's filter comes from. */
+    summaryRefName?: string;
     /** Applies one column's filter. Without it a mapped column still renders, but as a plain tile. */
     onSelect?: (setting: QuerySetting, column: string) => void;
     /** The filter key the listing is showing, so a tile stops looking active once the toolbar moves off it. */
@@ -16,4 +21,4 @@ export interface DashboardProps<T extends string, State> {
     presents?: string[];
     hidePresents?: boolean;
 }
-export default function Dashboard<T extends string, State>({ className, summary, queryMap, onSelect, queryKey, columns, presents, hidePresents, }: DashboardProps<T, State>): import("react/jsx-runtime").JSX.Element | null;
+export default function Dashboard<T extends string, State>({ className, summary, slice, queryMap, summaryRefName, onSelect, queryKey, columns, presents, hidePresents, }: DashboardProps<T, State>): import("react/jsx-runtime").JSX.Element | null;

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

@@ -21,10 +21,15 @@ interface AdminPanelProps<T extends string, State, Input, Full extends {
     template?: any;
     unit?: any;
     view?: any;
-    /** Summary column to filter query. Only a column this map names becomes a link to its filtered listing. */
+    /**
+     * Overrides the filter a summary column applies. A column left out still narrows the listing when its own
+     * field declares one with `.meta(...)`.
+     */
     queryMap?: {
         [column: string]: QuerySetting;
     };
+    /** Model whose fields `summaryColumns` name. Defaults to the `summary` model the state key already implies. */
+    summaryRefName?: string;
     /** 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. */
@@ -34,5 +39,5 @@ export default function AdminPanel<RefName extends string, State, Input, Full ex
     id: string;
 }, Light extends {
     id: string;
-}>({ slice, components, queryMap, template, unit, view, summaryColumns, insightColumns, renderInsight, renderDashboard, ...props }: AdminPanelProps<RefName, State, Input, Full, Light>): import("react/jsx-runtime").JSX.Element;
+}>({ slice, components, queryMap, summaryRefName, template, unit, view, summaryColumns, insightColumns, renderInsight, renderDashboard, ...props }: AdminPanelProps<RefName, State, Input, Full, Light>): import("react/jsx-runtime").JSX.Element;
 export {};

package/ui/Data/Dashboard.tsx

@@ -1,5 +1,6 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
+import { fieldQueryMetaOf } from "akanjs/constant";
 import type { QuerySetting, SliceMeta } from "akanjs/fetch";
 import { st } from "akanjs/store";
 import { useState } from "react";
@@ -11,8 +12,13 @@ export interface DashboardProps<T extends string, State> {
   summary: Record<string, unknown>;
   /** The listing these tiles belong to. Kept so a caller names its target; the labels are app-level keys. */
   slice: SliceMeta;
-  /** Columns that narrow the listing when clicked. A column absent from the map renders as a plain tile. */
+  /**
+   * Overrides the filter a column applies. A column left out still narrows the listing when its own field
+   * declares a query with `.meta(...)`; one with neither renders as a plain tile.
+   */
   queryMap?: { [column: string]: QuerySetting };
+  /** Model whose fields the columns name. Its `.meta(...)` declarations are where a tile's filter comes from. */
+  summaryRefName?: string;
   /** Applies one column's filter. Without it a mapped column still renders, but as a plain tile. */
   onSelect?: (setting: QuerySetting, column: string) => void;
   /** The filter key the listing is showing, so a tile stops looking active once the toolbar moves off it. */
@@ -27,7 +33,9 @@ const tileClassName = "flex min-w-40 flex-1 flex-col gap-1 rounded-box border px
 export default function Dashboard<T extends string, State>({
   className,
   summary,
+  slice,
   queryMap,
+  summaryRefName = "summary",
   onSelect,
   queryKey,
   columns,
@@ -39,14 +47,21 @@ export default function Dashboard<T extends string, State>({
   const filter = Array.isArray(searchParams.filter) ? searchParams.filter[0] : searchParams.filter;
 
   const [selected, setSelected] = useState(typeof filter === "string" ? filter : undefined);
+
+  const settingOf = (column: string): QuerySetting | undefined => {
+    if (queryMap?.[column]) return queryMap[column];
+    const meta = fieldQueryMetaOf(summaryRefName, column);
+    if (!meta?.queryKey || meta.refName !== slice.refName) return undefined;
+    return { queryKey: meta.queryKey, args: meta.queryArgs };
+  };
   const shownColumns = (columns ?? []).filter((column) => summary[column] !== undefined);
   const shownPresents = hidePresents ? [] : (presents ?? []).filter((column) => summary[column] !== undefined);
   if (!shownColumns.length && !shownPresents.length) return null;
-  const activeColumn = selected && queryMap?.[selected]?.queryKey === queryKey ? selected : undefined;
+  const activeColumn = selected && settingOf(selected)?.queryKey === queryKey ? selected : undefined;
   return (
     <div className={cn("mb-4 flex flex-wrap gap-2", className)}>
       {[...shownColumns, ...shownPresents].map((column) => {
-        const setting = queryMap?.[column];
+        const setting = settingOf(column);
         const label = dictLabel(l._, `summary.${column}`, column);
         const body = (
           <>

package/ui/Model/AdminPanel.tsx

@@ -17,8 +17,13 @@ interface AdminPanelProps<T extends string, State, Input, Full extends { id: str
   template?: any;
   unit?: any;
   view?: any;
-  /** Summary column to filter query. Only a column this map names becomes a link to its filtered listing. */
+  /**
+   * Overrides the filter a summary column applies. A column left out still narrows the listing when its own
+   * field declares one with `.meta(...)`.
+   */
   queryMap?: { [column: string]: QuerySetting };
+  /** Model whose fields `summaryColumns` name. Defaults to the `summary` model the state key already implies. */
+  summaryRefName?: string;
   /** 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. */
@@ -35,6 +40,7 @@ export default function AdminPanel<
   slice,
   components,
   queryMap,
+  summaryRefName,
   template,
   unit,
   view,
@@ -51,6 +57,7 @@ export default function AdminPanel<
           slice={slice}
           columns={summaryColumns}
           queryMap={queryMap}
+          summaryRefName={summaryRefName}
           onSelect={onSelect}
           queryKey={queryKey}
           hidePresents={hidePresents}