@declarion/react 0.1.76 → 0.1.78

package/dist-lib/lib/actions.d.ts

@@ -1,4 +1,4 @@
-import type { Action, ActionCondition, Schema } from "../types/schema";
+import type { Action, ActionCondition, LocalizedString, Schema } from "../types/schema";
 /**
  * Evaluates action conditions against row data.
  * Returns true if the action is available (all conditions pass).
@@ -34,6 +34,8 @@ export declare function actionHasParams(action: Action): boolean;
 export declare function fullActionCode(entityCode: string | undefined, actionCode: string): string;
 /**
  * Checks if an action is an association navigation action.
+ * Reason: per new wire format (unified-toolbar plan §1-§2), dispatch mode is
+ * encoded by which dispatch field is set; the `association` field is the mode.
  */
 export declare function isAssociationAction(action: Action): boolean;
 /**
@@ -44,3 +46,98 @@ export declare function findListScreenForEntity(schema: Schema | undefined, enti
     route: string;
     icon: string;
 } | undefined;
+/**
+ * Resolved leaf node. Kind discriminator "action".
+ * Enabled defaults true from server; client sets false when enabled_if fails.
+ * Reason carries the localized tooltip text when Enabled is false.
+ *
+ * Wire format (plan §8): {"kind":"action","code":"approve","enabled":true,"reason":null}
+ */
+export interface ResolvedActionLeaf {
+    kind: "action";
+    code: string;
+    enabled: boolean;
+    reason: string | null;
+}
+/**
+ * Resolved group node. Kind discriminator "group".
+ * Items is always non-empty after pruning (empty groups are dropped).
+ *
+ * Wire format (plan §8): {"kind":"group","name":{...},"icon":"...","items":[...]}
+ */
+export interface ResolvedActionGroup {
+    kind: "group";
+    name?: LocalizedString;
+    icon?: string;
+    items: ResolvedActionLayoutNode[];
+}
+/**
+ * Discriminated union for a resolved action layout node.
+ * Narrow via node.kind === "action" or node.kind === "group".
+ */
+export type ResolvedActionLayoutNode = ResolvedActionLeaf | ResolvedActionGroup;
+/**
+ * applyRowState walks an RBAC-pruned ResolvedActionLayoutNode[] and applies
+ * per-row visible_if / enabled_if evaluation (plan §4, §5).
+ *
+ * Drop conditions:
+ * - visible_if conditions not satisfied by row -> leaf dropped
+ * - Empty groups after all children are dropped -> group dropped
+ *
+ * Disable conditions:
+ * - enabled_if conditions not satisfied by row -> leaf enabled=false + reason set
+ * - For bulk (rowSelection.length > 1): disabled if ANY selected row fails enabled_if
+ *   (plan §5: "disabled if ANY row fails"). Reason is from the first failing row.
+ *
+ * @param layout   RBAC-pruned tree from the server (or resolveActionLayout client-side).
+ * @param entityActions  Entity-level actions map (entity wins on code collision).
+ * @param globalActions  Global schema actions (fallback when entity doesn't declare).
+ * @param row      The current row data for single-row context (detail / list_row).
+ * @param rowSelection  All selected rows for bulk context (list_toolbar bulk mode).
+ *                      Pass empty array for non-bulk contexts.
+ */
+export declare function applyRowState(layout: ResolvedActionLayoutNode[], entityActions: Record<string, Action> | undefined, globalActions: Record<string, Action> | undefined, row: Record<string, unknown>, rowSelection: Record<string, unknown>[]): ResolvedActionLayoutNode[];
+/**
+ * Composes a flat ResolvedActionLayoutNode[] from an entity's actions map,
+ * filtered to those that include the given slot in their visibility array,
+ * sorted by position ascending (ties broken by declaration order).
+ *
+ * This is the fallback used when neither screen.action_layout nor
+ * entity.action_layout is present (plan §3: "runtime MUST compose a flat
+ * layout from all actions matching the slot's visibility[], sorted by
+ * position ascending").
+ *
+ * All leaves are emitted with enabled=true; client applies visible_if /
+ * enabled_if via applyRowState.
+ *
+ * @param actions  Entity-level actions map from the (already RBAC-pruned) schema.
+ * @param slot     Placement slot code (e.g. "detail", "list_row", "list_toolbar").
+ */
+/**
+ * Filters a server-emitted ResolvedActionLayoutNode tree to a single slot,
+ * preserving group structure. Drops leaves whose action's visibility[] does
+ * not include the slot. Drops groups whose entire item list pruned out
+ * (plan §5 empty-group auto-hide). Additional filters via `opts`:
+ *
+ *  - opts.bulkRequired: when set, gates list_toolbar leaves whose effective
+ *    "bulk-required" semantic matches the request. The old wire-format flag
+ *    `bulk_selection_required` was removed in unified-toolbar Phase 1 (the
+ *    server now derives this from `handler.invoke`); until Task 38 replaces
+ *    this code path the caller passes a predicate that decides per action.
+ *    Reason: keep the slot+bulk filtering surface intact while removing the
+ *    field; the call sites supply the legacy predicate.
+ *  - opts.excludeIf: drop leaves where the predicate returns true. Common
+ *    use: hide "create" / "edit" / "delete" style actions that the screen
+ *    renders inline elsewhere. Reason: the old `excludeTypes` keyed on
+ *    `action.type`, which is removed; callers now express the same intent
+ *    as a field-presence predicate.
+ *
+ * Leaves whose code cannot be looked up are dropped (server should have
+ * pruned them; defensive).
+ */
+export declare function filterLayoutForSlot(layout: ResolvedActionLayoutNode[], entityActions: Record<string, Action> | undefined, globalActions: Record<string, Action> | undefined, slot: string, opts?: {
+    bulkRequired?: boolean;
+    bulkRequiredPredicate?: (action: Action) => boolean;
+    excludeIf?: (action: Action) => boolean;
+}): ResolvedActionLayoutNode[];
+export declare function defaultFlatForSlot(actions: Record<string, Action> | undefined, slot: string): ResolvedActionLayoutNode[];

package/dist-lib/lib/children-validation.d.ts

@@ -1,3 +1,4 @@
-import type { Schema } from "../types/schema";
+import type { Entity, Schema } from "../types/schema";
 import type { PendingChildRow } from "../components/detail-layout/LayoutRenderer";
+export declare function findMissingRequiredFields(entity: Entity, formData: Record<string, unknown>, isNew: boolean): string[];
 export declare function validatePendingChildren(pendingChildren: Record<string, PendingChildRow[]> | undefined, schema: Schema | undefined): Record<string, Record<string, string[]>>;

package/dist-lib/lib/utils.d.ts

@@ -1,2 +1,9 @@
 import { type ClassValue } from "clsx";
 export declare function cn(...inputs: ClassValue[]): string;
+export declare function isModifiedClick(e: {
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    button: number;
+}): boolean;

package/dist-lib/types/fieldType.d.ts

@@ -1,2 +1,2 @@
-export type FieldType = "uuid" | "string" | "text" | "rich_text" | "int" | "float" | "bool" | "date" | "time" | "timestamp" | "email" | "url" | "phone" | "enum" | "json" | "ref" | "tags" | "multilang" | "multilang_text" | "structure" | "secret" | "password" | "decimal" | "string_array" | "int_array";
+export type FieldType = "uuid" | "string" | "text" | "rich_text" | "int" | "float" | "bool" | "date" | "time" | "timestamp" | "email" | "url" | "phone" | "enum" | "json" | "ref" | "tags" | "multilang" | "multilang_text" | "structure" | "secret" | "password" | "decimal" | "string_array" | "int_array" | "bytes";
 export declare const FIELD_TYPES: readonly FieldType[];

package/dist-lib/types/schema.d.ts

@@ -27,6 +27,11 @@ export declare function getDisplayValue(row: Record<string, unknown> | null | un
         display_field?: string;
     };
 } | null | undefined): string | undefined;
+export declare function resolveRefRecordLabel(record: Record<string, unknown>, displayField: string | undefined, fallback: string): string;
+export declare function screenTitleForPath(pathname: string, screens: Record<string, Screen> | undefined): {
+    title: string;
+    icon?: string;
+} | undefined;
 export declare function fieldDisplayName(field: EntityField, fieldName: string, entities?: Record<string, Entity>): string;
 export interface RefDisplay {
     field: string;
@@ -262,6 +267,13 @@ export interface Entity {
     /** Whether the entity participates in RBAC permission gating
      *  (`entity:<code>:<op>` grants). Mirrors engine.Entity.Permissions. */
     permissions?: boolean;
+    /**
+     * Optional structural tree for placing and grouping actions across all
+     * placement slots. Absent = runtime composes a flat list from all actions
+     * matching each slot's visibility[], sorted by position ascending.
+     * Server delivers RBAC-pruned nodes in tagged-union wire format (plan §8).
+     */
+    action_layout?: ActionLayoutNode[];
 }
 export interface ExportConfig {
     enabled?: boolean;
@@ -377,10 +389,11 @@ export interface Screen {
     detail_screen?: string;
     fixed_filters?: Record<string, unknown>;
     views?: ViewDefinition[];
-    /** Action slot promotion (rule-of-2). UI honors first 2. */
+    /** Action slot promotion for list screens (rule-of-2). UI honors first 2.
+     *  Note: primary_record_actions (detail header) was removed in Task 5 of plan
+     *  2026-04-21-action-toolbar-priority-overflow. Use action_layout instead. */
     primary_actions?: string[];
     primary_bulk_actions?: string[];
-    primary_record_actions?: string[];
     /** "open" (default) navigates to detail; "peek" opens QuickPeek drawer. */
     on_row_click?: "open" | "peek";
     quick_peek?: QuickPeekConfig;
@@ -391,6 +404,13 @@ export interface Screen {
      *  Either gate being false hides the toolbar Export menu and makes the
      *  POST endpoint return 403 EXPORT_DISABLED. */
     export?: ExportConfig;
+    /**
+     * Optional per-screen structural tree for placing and grouping actions.
+     * When set, fully replaces entity.action_layout for this screen.
+     * Absent = inherit entity.action_layout (then default-flat if also absent).
+     * Server delivers RBAC-pruned nodes in tagged-union wire format (plan §8).
+     */
+    action_layout?: ActionLayoutNode[];
 }
 export interface QuickPeekConfig {
     enabled?: boolean;
@@ -508,28 +528,147 @@ export interface UIStep {
     focus_field?: string;
     show_toast?: UIShowToastStep;
 }
+/**
+ * Leaf node in an action_layout tree. References a single action by code.
+ * Wire format (plan §8): {"kind": "action", "code": "<code>"}
+ */
+export interface ActionLayoutLeaf {
+    kind: "action";
+    code: string;
+}
+/**
+ * Branch node in an action_layout tree. Groups child nodes under a labelled dropdown.
+ * Wire format (plan §8): {"kind": "group", "name": {...}, "icon": "...", "items": [...]}
+ * Items is always non-empty (enforced by loader).
+ */
+export interface ActionLayoutGroup {
+    kind: "group";
+    name?: LocalizedString;
+    icon?: string;
+    items: ActionLayoutNode[];
+}
+/**
+ * Discriminated union of all action_layout tree nodes.
+ * Narrow via `node.kind === "action"` (leaf) or `node.kind === "group"` (branch).
+ */
+export type ActionLayoutNode = ActionLayoutLeaf | ActionLayoutGroup;
+/**
+ * Single row-state condition for visible_if / enabled_if / conditions.
+ * Operators: eq | ne | in | not_in | gt | lt | ge | le.
+ */
+export interface ActionConditionEntry {
+    field?: string;
+    op?: string;
+    value?: unknown;
+    status?: string[];
+}
+/**
+ * Array of row-state conditions with AND semantics. YAML accepts both single
+ * object and array form (see Go ActionConditionList unmarshal); wire format
+ * from server is always array (server normalizes during schema response).
+ */
+export type ActionConditionList = ActionConditionEntry[];
 export interface Action {
+    /**
+     * Server-side handler code. One of four dispatch fields - see plan §1-§2.
+     * Reason: the new wire format encodes dispatch mode by which field is set
+     * (handler | association | widget | href), so an explicit `type` enum is
+     * redundant and was removed. Exactly one of the four should be set per action.
+     */
     handler?: string;
-    type?: string;
+    /**
+     * Association code for nav-only actions that navigate to a related list.
+     * Reason: same dispatch-by-field-presence rule; see plan §1-§2.
+     */
     association?: string;
+    /**
+     * SDK widget registry name. Phase 2 wires the registry; today the field
+     * is plumbed through the schema and consumed by Task 38's toolbar pipeline.
+     * Reason: lets actions render bespoke UI (e.g. inline picker) instead of
+     * server-handled forms, without inventing a new entity per widget.
+     */
+    widget?: string;
+    /**
+     * Client-side navigation URL template (supports `${id}` and other row tokens).
+     * Reason: replaces the implicit "edit"/"create" type enum - any href-driven
+     * action (open a custom screen, deep-link a report) uses this field; the
+     * server never dispatches it.
+     */
+    href?: string;
+    /**
+     * Widget-specific opaque metadata. Schema/Action loader passes through
+     * untouched; the widget consumes its own keys.
+     * Reason: keeps the Action shape stable as new widgets ship without
+     * growing the typed surface for each one.
+     */
+    config?: Record<string, unknown>;
     entity?: string;
     display: {
         name: LocalizedString;
         icon: string;
+        /**
+         * Promotes the action to a header button (vs. dropdown item).
+         * Reason: explicit per-action UX control replaces the old position<=10
+         * heuristic, lets schema authors mark their headline action even when
+         * other actions sort earlier.
+         */
+        primary?: boolean;
+        /**
+         * Render as icon-only button (no label text).
+         * Reason: lets a dense toolbar host high-frequency actions without
+         * cluttering the bar with labels; tooltip still shows display.name.
+         */
+        icon_only?: boolean;
+        /**
+         * Button size hint. Default "md".
+         * Reason: secondary toolbars (associated blocks, inline editors) need
+         * smaller buttons than primary header bars - the schema author picks.
+         */
+        size?: "sm" | "md" | "lg";
+        /**
+         * Keyboard shortcut hint (e.g. "Cmd+S"). Rendered in tooltip/menu.
+         * Reason: discoverability for power users; binding is wired in Task 38.
+         */
+        shortcut?: string;
+        /**
+         * Localized help text for tooltip/popover.
+         * Reason: separate from display.name so the title stays terse while a
+         * longer explanation surfaces on hover.
+         */
+        help?: LocalizedString;
     };
     visibility?: string[];
     confirmation?: LocalizedString;
     conditions?: ActionCondition[];
-    /** Promote to header/bulk-bar button (max 2 per slot honored by UI). */
-    primary?: boolean;
+    /**
+     * Ordering within a placement slot and overflow priority. Lower = earlier
+     * in bar AND last to overflow. Default 0; ties broken by declaration order.
+     * Step-10 convention. See plan §1 and §3.
+     */
+    position?: number;
+    /**
+     * Hide the action when condition does not hold against current row.
+     * Distinct from RBAC hide and from `enabled_if` disable. AND semantics
+     * across array elements. See plan §1, §5.
+     */
+    visible_if?: ActionConditionList;
+    /**
+     * Disable the action (greyed out + tooltip) when condition does not hold.
+     * For bulk-mode multi-row selection, disabled if ANY selected row fails.
+     * See plan §1, §5.
+     */
+    enabled_if?: ActionConditionList;
+    /**
+     * Localized tooltip shown when action is disabled by `enabled_if`.
+     * Required when `enabled_if` is set (loader validates in Task 3).
+     */
+    enabled_if_reason?: LocalizedString;
     /** Forces confirm + danger styling. */
     destructive?: boolean;
     /** UI shows a toast instead of a blocking result modal; adds a navigation link if progress_screen is set. */
     long_running?: boolean;
     /** Screen code to navigate to after a long_running action starts (resolved via schema.screens). */
     progress_screen?: string;
-    /** When true, action shown grayed until >=1 row selected. */
-    bulk_selection_required?: boolean;
     resolved_params?: OrderedMap<HandlerParam>;
     /**
      * Default values of params marked hidden+default by the action. The UI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",
@@ -66,6 +66,7 @@
     "zustand": "^5.0.0"
   },
   "devDependencies": {
+    "@axe-core/react": "^4.11.3",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.2.4",
     "@testing-library/dom": "^10.4.1",
@@ -75,6 +76,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",
+    "axe-core": "^4.11.4",
     "eslint": "^10.2.1",
     "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^29.0.1",

package/dist-lib/components/detail/DetailPage.d.ts

@@ -1,30 +0,0 @@
-import { type ReactNode } from "react";
-import { type Action, type Screen } from "../../types/schema";
-export type DetailMode = "view" | "edit" | "create";
-export interface DetailPageProps {
-    mode: DetailMode;
-    onModeChange: (m: DetailMode) => void;
-    onClose: () => void;
-    onSave: () => void | Promise<void>;
-    onDelete?: () => void;
-    title: string;
-    recordId?: string;
-    /** When true, opens in edit mode with the dirty badge — used by peek-promote. */
-    initialDirty?: boolean;
-    dirty: boolean;
-    /** Optional sub-header row (pipeline / priority / source / score chips). */
-    subHeader?: ReactNode;
-    /** Avatar or leading badge rendered before the title. */
-    leading?: ReactNode;
-    /** Full YAML screen so primary_record_actions is honored. */
-    screen?: Screen;
-    /** Actions available on this record (resolved from entity + screen). */
-    actions: Record<string, Action>;
-    executeAction: (code: string, action: Action, params: Record<string, unknown>) => Promise<unknown>;
-    /** Optional right-rail slot — maps to the design's ActivityPanel / sidebar. */
-    sidebar?: ReactNode;
-    /** Optional footer metadata strip ("Created … · Updated … · Version 7"). */
-    footerMeta?: ReactNode;
-    children?: ReactNode;
-}
-export declare function DetailPage({ mode, onModeChange, onClose, onSave, onDelete, title, recordId, initialDirty, dirty, subHeader, leading, screen, actions, executeAction, sidebar, footerMeta, children, }: DetailPageProps): import("react/jsx-runtime").JSX.Element;