@cosmicdrift/kumiko-framework 0.373.0 → 0.374.0

package/agents/widgets.md

@@ -118,6 +118,7 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | `useDraft` | Formular-State für Rechner-Screens: ein Draft-Objekt + `patch` für Teil-Updates + `field(name)` das die `{ id, name, value, onChange }`-Props fertig für die Feld-Widgets (NumberField/MoneyField/PercentField) liefert. |
 | `useForm` |  |
 | `useIsNarrowViewport` |  |
+| `useIsViewportBelow` |  |
 | `useLiveEvents` | Hook für useQuery-like Consumer. |
 | `useLocale` | Liefert den aktuellen LocaleResolver und abonniert automatisch Locale-Änderungen — der aufrufende Component re-rendert sobald die Sprache gewechselt wird. |
 | `useNav` |  |

package/dist/engine/boot-validator/projection-list-screens.js

@@ -1,5 +1,5 @@
-import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
-import { parseQn, QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
+import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
 import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../types/index.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
@@ -28,28 +28,38 @@ function schemaAccepts(schema, key) {
     const shape = getZodObjectShape(schema);
     return shape !== undefined && key in shape;
 }
-function validateOneProjectionListScreen(feature, screen, queryHandlers) {
+// sortable/paginated are derived by buildAppSchema from the query's Zod
+// schema (fw#2165) — there is no separate wire type from the author-facing
+// ProjectionListScreenDefinition, so hand-authoring them would otherwise be
+// silently overwritten with no signal to the author. Reject outright.
+function rejectHandAuthoredDerivedFlags(prefix, screen) {
+    if (screen.sortable !== undefined) {
+        throw new Error(`${prefix}: sortable is derived from the query's Zod schema, don't set it`);
+    }
+    if (screen.paginated !== undefined) {
+        throw new Error(`${prefix}: paginated is derived from the query's Zod schema, don't set it`);
+    }
+}
+function validateOneProjectionListScreen(feature, screen, queryHandlers, featureMap) {
     const prefix = `[projectionList] Feature "${feature.name}" screen "${screen.id}"`;
-    const schema = queryHandlers.get(screen.query)?.schema;
+    const handler = queryHandlers.get(screen.query);
+    const schema = handler?.schema;
+    // buildAppSchema derives searchable: false for these, so no whitelist entry is needed.
+    const searchDerivedOff = isListQueryWithoutSearchableFields(screen.query, handler, (name) => findEntity(featureMap, name));
     if (screen.searchable === true && !schemaAccepts(schema, "search")) {
         throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
     }
+    if (screen.searchable === true && searchDerivedOff) {
+        throw new Error(`${prefix}: searchable: true but query "${screen.query}" lists an entity with no searchable field, so a search would never match. Mark a field searchable: true on the entity or remove searchable: true.`);
+    }
     if (screen.searchable === false &&
         schemaAccepts(schema, "search") &&
+        !searchDerivedOff &&
         !SEARCHABLE_FALSE_WHITELIST.has(screen.id)) {
         throw new Error(`${prefix}: query "${screen.query}" accepts "search" but searchable: false disables it — remove searchable: false or add "${screen.id}" to SEARCHABLE_FALSE_WHITELIST`);
     }
-    // sortable/paginated are derived by buildAppSchema from the query's Zod
-    // schema (fw#2165) — there is no separate wire type from the author-facing
-    // ProjectionListScreenDefinition, so hand-authoring them would otherwise be
-    // silently overwritten with no signal to the author. Reject outright.
-    if (screen.sortable !== undefined) {
-        throw new Error(`${prefix}: sortable is derived from the query's Zod schema, don't set it`);
-    }
-    if (screen.paginated !== undefined) {
-        throw new Error(`${prefix}: paginated is derived from the query's Zod schema, don't set it`);
-    }
-    const searchActive = screen.searchable !== false && schemaAccepts(schema, "search");
+    rejectHandAuthoredDerivedFlags(prefix, screen);
+    const searchActive = screen.searchable !== false && !searchDerivedOff && schemaAccepts(schema, "search");
     const sortActive = schemaAccepts(schema, "sort");
     if ((searchActive || sortActive) && screen.defaultSort === undefined) {
         throw new Error(`${prefix}: defaultSort required when search or sort is active. Set defaultSort: { field, direction }.`);
@@ -132,11 +142,12 @@ function validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema) {
 }
 export function validateProjectionListScreens(features) {
     const queryHandlers = buildQueryHandlerMap(features);
+    const featureMap = new Map(features.map((f) => [f.name, f]));
     for (const feature of features) {
         for (const screen of Object.values(feature.screens)) {
             if (screen.type !== "projectionList")
                 continue;
-            validateOneProjectionListScreen(feature, screen, queryHandlers);
+            validateOneProjectionListScreen(feature, screen, queryHandlers, featureMap);
         }
     }
 }
@@ -155,26 +166,6 @@ function validateRelatedListFacets(prefix, section, schema) {
         return;
     throw new Error(`${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
 }
-// parentFilter resolves an entity field map to
-// check `field` against ONLY when the query is one of the entity-convention
-// factories (defineEntityListHandler et al., branded by
-// ENTITY_CONVENTION_QUERY_BRAND) — a hand-written handler carries no entity,
-// same "capability absent, no throw" policy as schemaAccepts above. The
-// entity name comes from the handler's own `<entityName>:list` naming
-// convention (parseHandlerName in entity-handlers.ts), recovered here from
-// the query's fully qualified name.
-function resolveEntityBehindQuery(queryQn, handler, featureMap) {
-    if (handler === undefined || handler[ENTITY_CONVENTION_QUERY_BRAND] !== true)
-        return undefined;
-    let entityName;
-    try {
-        entityName = parseQn(queryQn).name.split(":")[0] ?? "";
-    }
-    catch {
-        return undefined;
-    }
-    return entityName === "" ? undefined : findEntity(featureMap, entityName);
-}
 // parentFilter lets a relatedList reuse the
 // generic `<entity>:list` query instead of a bespoke child-rows handler —
 // same 422 footgun as facets/filter above, plus its own mutual-exclusivity
@@ -193,7 +184,7 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
             `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
             `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
     }
-    const entity = resolveEntityBehindQuery(section.query, handler, featureMap);
+    const entity = resolveEntityBehindListQuery(section.query, handler, (name) => findEntity(featureMap, name));
     if (entity !== undefined && entity.fields[section.parentFilter.field] === undefined) {
         throw new Error(`${prefix}: parentFilter.field "${section.parentFilter.field}" is not a declared field on the ` +
             `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);

package/dist/engine/boot-validator/query-refs.js

@@ -1,3 +1,4 @@
+import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
 import { buildQueryHandlerMap } from "./projection-list-screens.js";
 const NOT_REGISTERED_SUFFIX = "is not a registered query-handler. Check the QN spelling (expected " +
     '"<feature>:query:<short>") and that the handler is declared via r.queryHandler(...).';
@@ -29,19 +30,30 @@ function checkVisibleWhenQueryRef(queryHandlers, query, buildPrefix) {
 // types) keeps this collector correct if that restriction is ever lifted.
 function checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screenType, layout) {
     for (const section of layout.sections) {
+        if (isFieldsEditSection(section)) {
+            for (const fieldSpec of sectionFieldSpecs(section)) {
+                const { field, fillAction } = normalizeEditField(fieldSpec);
+                if (fillAction === undefined)
+                    continue;
+                checkQueryRef(queryHandlers, fillAction.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${field}" fillAction`);
+            }
+        }
         if (section.kind !== "relatedList")
             continue;
         checkQueryRef(queryHandlers, section.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}"`);
     }
 }
 function checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen) {
+    if (screen.record?.query !== undefined) {
+        checkQueryRef(queryHandlers, screen.record.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) record`);
+    }
     for (const panel of screen.panels) {
         if (panel.kind === "custom")
             continue;
         if (panel.visibleWhen !== undefined) {
             checkVisibleWhenQueryRef(queryHandlers, panel.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) ${panel.kind === "screen" ? "screen-panel" : "panel"} "${panel.id}" visibleWhen`);
         }
-        if (panel.kind === "screen")
+        if (panel.kind === "screen" || panel.kind === "text")
             continue;
         if (panel.kind === "stat-group") {
             for (const stat of panel.stats) {
@@ -70,6 +82,18 @@ function checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screenTyp
         }
     }
 }
+function checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
+    checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.layout);
+    if (screen.type === "actionForm" && screen.load !== undefined) {
+        checkQueryRef(queryHandlers, screen.load.query, () => `[Feature ${featureName}] Screen "${screenId}" (actionForm) load`);
+    }
+    if (screen.type !== "entityEdit") {
+        checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.fields);
+    }
+    if (screen.type === "secretMint" && screen.confirm !== undefined) {
+        checkFormFieldQueryRefs(queryHandlers, featureName, screenId, "secretMint confirm", screen.confirm.fields);
+    }
+}
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
     if (screen.visibleWhen !== undefined) {
         checkVisibleWhenQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
@@ -90,13 +114,7 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
         screen.type === "actionForm" ||
         screen.type === "configEdit" ||
         screen.type === "secretMint") {
-        checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.layout);
-        if (screen.type !== "entityEdit") {
-            checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.fields);
-        }
-        if (screen.type === "secretMint" && screen.confirm !== undefined) {
-            checkFormFieldQueryRefs(queryHandlers, featureName, screenId, "secretMint confirm", screen.confirm.fields);
-        }
+        checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, screen);
     }
     else if (screen.type === "dashboard") {
         checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen);

package/dist/engine/boot-validator/screens.d.ts

@@ -3,7 +3,7 @@ import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.ts";
 import type { ActionFormScreenDefinition, DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.ts";
 export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
 export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
-export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList", context: string, action: {
+export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList" | "dashboard", context: string, action: {
     readonly id: string;
     readonly icon?: IconKey;
 }): void;