@object-ui/core 17.1.0 → 17.2.0

package/dist/utils/managedBy.js

@@ -1,38 +1,50 @@
 /**
- * managedBy — the single source of truth for interpreting an object's
- * lifecycle bucket (`ObjectSchema.managedBy`) into CRUD affordances.
+ * managedBy — the UI end of the platform's `managedBy` → CRUD affordance
+ * contract (ADR-0103).
  *
- * UI-side mirror of the framework's `resolveCrudAffordances()`
- * (`@objectstack/spec/data/object.zod.ts`, ADR-0103). Lives in `@object-ui/core`
- * — React-free and reachable by every UI package (app-shell, plugin-detail,
- * plugin-form, plugin-grid) — so the bucket logic is defined ONCE instead of
- * hand-mirrored in each. Components ask "should I show New / Import / Edit /
- * Delete / Export?" and get an answer that tracks the object's lifecycle without
- * special-casing `sys_*` names.
+ * ## What is spec-owned here, and what is not (objectstack#4115)
  *
- * The bucket UNION type lives in `@object-ui/types` (`ManagedByBucket`) so the
- * schema field can reference it; this module re-exports it for convenience.
- * Only the affordance BOOLEANS live here — all translated copy (badge variants,
- * empty-state messages) stays in `@object-ui/app-shell`.
+ * The bucket logic is **the spec's**, and this module now says so in code
+ * rather than in a comment. `CrudAffordances` / `RowCrudPredicates` are
+ * re-exported from `@objectstack/spec/data`, and the bucket resolution itself
+ * delegates to the spec's `resolveCrudAffordances()`.
+ *
+ * This module used to describe itself as a "UI-side mirror" of that function
+ * and carry its own `DEFAULTS` table — a line-for-line copy of the spec's
+ * `CRUD_AFFORDANCE_DEFAULTS`, plus a copy of its override parser. A faithful
+ * copy passes every value comparison and every behavioural test, so nothing
+ * would have caught the release in which the spec re-buckets an object class;
+ * reference identity is the only check that distinguishes a re-export from a
+ * fork (objectui#3003).
+ *
+ * What is genuinely objectui's and keeps a local name:
+ * {@link resolveEffectiveCrudAffordances} — the spec's object-level matrix
+ * INTERSECTED with the server-resolved effective API operation set (#3391), so
+ * the UI never offers a button the server would 405. The spec's function has
+ * no such notion; naming ours after it was the misdescription this burn-down
+ * removes.
+ *
+ * Lives in `@object-ui/core` — React-free and reachable by every UI package
+ * (app-shell, plugin-detail, plugin-form, plugin-grid) — so the intersection is
+ * defined ONCE instead of hand-mirrored in each. The bucket UNION type lives in
+ * `@object-ui/types` (`ManagedByBucket`) and is re-exported here for
+ * convenience. All translated copy (badge variants, empty-state messages) stays
+ * in `@object-ui/app-shell`.
  */
-const DEFAULTS = {
-    platform: { create: true, import: true, edit: true, delete: true, exportCsv: true },
-    config: { create: true, import: false, edit: true, delete: true, exportCsv: true },
-    system: { create: false, import: false, edit: false, delete: false, exportCsv: true },
-    'engine-owned': { create: false, import: false, edit: false, delete: false, exportCsv: true },
-    'append-only': { create: false, import: false, edit: false, delete: false, exportCsv: true },
-    'better-auth': { create: false, import: false, edit: false, delete: false, exportCsv: true },
-};
+import { resolveCrudAffordances as resolveSpecCrudAffordances, } from '@objectstack/spec/data';
 /**
  * Collapse an `edit`/`delete` override (boolean or #2614 object form) onto
  * the given bucket default, surfacing any per-record predicates alongside.
  *
  * THE single parser for the `userActions.{edit,delete}` override shape — every
- * UI package (grid row affordances, related-list row predicates, this module's
- * own `resolveCrudAffordances`) routes through here instead of re-implementing
- * the boolean/object-form parse locally. `base` is the bucket default an
- * omitted `enabled` falls back to (callers that only gate on an explicit
- * opt-out pass `true`; predicate extraction is independent of `base`).
+ * UI package (grid row affordances, related-list row predicates) routes through
+ * here instead of re-implementing the boolean/object-form parse locally. The
+ * spec keeps its equivalent (`normalizeRowCrudOverride`) module-private, so
+ * this stays a local declaration — under a name the spec does not own.
+ *
+ * `base` is the bucket default an omitted `enabled` falls back to (callers that
+ * only gate on an explicit opt-out pass `true`; predicate extraction is
+ * independent of `base`).
  */
 export function normalizeUserAction(v, base) {
     if (v == null)
@@ -73,7 +85,15 @@ const AFFORDANCE_TO_API_OPERATION = {
     exportCsv: 'export',
 };
 /**
- * Resolve the effective CRUD affordances for an object schema.
+ * Resolve the CRUD affordances a UI surface should expose for an object —
+ * the spec's object-level matrix, INTERSECTED with what the server will
+ * actually accept.
+ *
+ * The bucket/`userActions` half is **not computed here**: it is delegated to
+ * `resolveCrudAffordances()` from `@objectstack/spec/data` (ADR-0103), so the
+ * bucket table has exactly one definition on the platform. Only the
+ * intersection below is objectui's, which is why this function no longer
+ * carries the spec's name (objectstack#4115).
  *
  * @param obj The object schema (managedBy bucket + userActions overrides).
  * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
@@ -84,23 +104,15 @@ const AFFORDANCE_TO_API_OPERATION = {
  *   (old backend / no effective set) leaves the affordances untouched —
  *   backward-compatible. An empty array means "expose nothing" → all bits off.
  */
-export function resolveCrudAffordances(obj, effectiveApiOperations) {
-    const bucket = obj?.managedBy ?? 'platform';
-    const base = DEFAULTS[bucket] ?? DEFAULTS.platform;
-    const o = obj?.userActions ?? {};
-    const edit = normalizeUserAction(o.edit, base.edit);
-    const del = normalizeUserAction(o.delete, base.delete);
-    const out = {
-        create: o.create ?? base.create,
-        import: o.import ?? base.import,
-        edit: edit.enabled,
-        delete: del.enabled,
-        exportCsv: o.exportCsv ?? base.exportCsv,
-    };
-    if (edit.predicates)
-        out.editPredicates = edit.predicates;
-    if (del.predicates)
-        out.deletePredicates = del.predicates;
+export function resolveEffectiveCrudAffordances(obj, effectiveApiOperations) {
+    // The spec's resolver is the single definition of the bucket defaults and the
+    // `userActions` override parse (including the #2614 object form). Its input
+    // type does not model the `null`s objectui's loosely-typed schemas carry, so
+    // they are normalised away at this one seam rather than re-deriving anything.
+    const out = resolveSpecCrudAffordances({
+        managedBy: obj?.managedBy ?? undefined,
+        userActions: (obj?.userActions ?? undefined),
+    });
     // [#3391] Intersect with the server's effective API operations when present.
     // The frontend consumes the effective set the server hands down; it never
     // reads the raw `apiMethods` nor re-derives.
@@ -118,15 +130,26 @@ export function isWriteOptedIn(v) {
     return v === true || (typeof v === 'object' && v !== null && v.enabled === true);
 }
 /**
- * ADR-0103 — a `system`-bucket object that opened ANY write via `userActions`
- * is admin/user-writable DATA, not an engine-owned monitoring surface. Used to
- * pick the writable-system badge/empty-state copy.
+ * True for a platform-defined schema whose DATA is admin/user-writable — the
+ * `system-data` bucket. Used to pick the writable-system badge/empty-state copy
+ * instead of the engine-owned "read-only monitoring surface" copy.
+ *
+ * **Simplified in protocol 17 (objectstack#3355).** Under ADR-0103's v16 split
+ * this had to RECOVER the distinction from `userActions`: `system` doubled as
+ * both the engine-owned default and the writable set, so "did it open any
+ * write?" was the only way to tell a Notification Preferences grid from an
+ * automation-run log. v17 retired that overload — the writable half is now the
+ * `system-data` bucket (writable by DEFAULT) and the engine-owned half is
+ * `engine-owned` — so the bucket answers the question directly and the
+ * `userActions` probe would only re-derive what the value already states.
+ *
+ * The narrowing case is deliberately still `true`: a `system-data` grid that
+ * narrows to edit-only is still platform-schema/user-data and should read as
+ * such. The spec refuses `system-data` on an object that narrows away every
+ * write, so there is no "writable bucket with no writes" shape to worry about.
  */
 export function isSystemWritable(obj) {
-    if (obj?.managedBy !== 'system')
-        return false;
-    const o = obj?.userActions ?? {};
-    return o.create === true || isWriteOptedIn(o.edit) || isWriteOptedIn(o.delete);
+    return obj?.managedBy === 'system-data';
 }
 /**
  * Whether an object's rows may be edited in place (detail inline-edit / form
@@ -143,5 +166,5 @@ export function isSystemWritable(obj) {
  *   bucket affordance untouched.
  */
 export function isObjectInlineEditable(obj, effectiveApiOperations) {
-    return resolveCrudAffordances(obj, effectiveApiOperations).edit;
+    return resolveEffectiveCrudAffordances(obj, effectiveApiOperations).edit;
 }

package/dist/utils/normalize-list-view.d.ts

@@ -5,10 +5,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { RowHeight } from '@objectstack/spec/ui';
 /** ListView's toolbar density vocabulary — three steps, not the spec's five. */
 export type DensityMode = 'compact' | 'comfortable' | 'spacious';
-/** The spec's `RowHeightSchema` vocabulary. */
-export type RowHeight = 'compact' | 'short' | 'medium' | 'tall' | 'extra_tall';
+/**
+ * The spec's `RowHeightSchema` vocabulary — **re-exported, not re-declared**.
+ *
+ * The hand-written union that used to sit here already advertised itself as
+ * "the spec's `RowHeightSchema` vocabulary" in its doc comment, which is the
+ * failure class objectstack#4115 is about: the claim was true when written and
+ * nothing would have caught the day it stopped being true. The maps below are
+ * `Record<RowHeight, …>`, so a spec-side addition now fails the build here
+ * instead of silently leaving a row height with no density mapping.
+ */
+export type { RowHeight };
 /**
  * `densityMode` → `rowHeight`. The two vocabularies are not the same size: the
  * spec has five row heights, ListView's toolbar offers three. Widening maps

package/dist/validation/index.d.ts

@@ -12,6 +12,7 @@
  * validation (`schema-validator.js`, `validation-engine.js`) is unaffected: it
  * is client-side form validation, not a mirror of a server rule.
  */
+export * from './required-presence.js';
 export * from './validation-engine.js';
 export * from './schema-validator.js';
 export * from './validators/index.js';

package/dist/validation/index.js

@@ -12,6 +12,7 @@
  * validation (`schema-validator.js`, `validation-engine.js`) is unaffected: it
  * is client-side form validation, not a mirror of a server rule.
  */
+export * from './required-presence.js';
 export * from './validation-engine.js';
 export * from './schema-validator.js';
 export * from './validators/index.js';

package/dist/validation/required-presence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The ONE client-side answer to "is this field's value absent?" for a
+ * `required` check.
+ *
+ * `required` is a PRESENCE contract, not a truthiness one. `@objectstack/spec`
+ * FieldSchema.required (ADR-0113) reads "an insert must provide a NON-NULL
+ * value", and objectql's record validator implements exactly that — its
+ * `isMissing` is `undefined | null | blank string`, nothing more. This mirrors
+ * that verdict so the form, the wizard's cross-step gate, and the server all
+ * agree instead of each inventing a dialect.
+ *
+ * What this deliberately does NOT treat as absent:
+ * - `false` — a boolean's second value. react-hook-form's own `required` rule
+ *   fails on `isBoolean(v) && !v`, which quietly turns a required checkbox into
+ *   "must be TRUE": an AI-built task tracker could not create an UNFINISHED
+ *   task, because the state the switch shows by default was the one value it
+ *   refused to save (cloud#972).
+ * - `0` — a number's identity element. "Zero hours logged" is data.
+ *
+ * An empty ARRAY *is* absent: the server has no array-valued scalar to
+ * disagree about, and "nothing picked" is a multiselect's own empty state,
+ * exactly as a blank string is a text input's.
+ */
+export declare function isMissingForRequired(value: unknown): boolean;

package/dist/validation/required-presence.js

@@ -0,0 +1,36 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The ONE client-side answer to "is this field's value absent?" for a
+ * `required` check.
+ *
+ * `required` is a PRESENCE contract, not a truthiness one. `@objectstack/spec`
+ * FieldSchema.required (ADR-0113) reads "an insert must provide a NON-NULL
+ * value", and objectql's record validator implements exactly that — its
+ * `isMissing` is `undefined | null | blank string`, nothing more. This mirrors
+ * that verdict so the form, the wizard's cross-step gate, and the server all
+ * agree instead of each inventing a dialect.
+ *
+ * What this deliberately does NOT treat as absent:
+ * - `false` — a boolean's second value. react-hook-form's own `required` rule
+ *   fails on `isBoolean(v) && !v`, which quietly turns a required checkbox into
+ *   "must be TRUE": an AI-built task tracker could not create an UNFINISHED
+ *   task, because the state the switch shows by default was the one value it
+ *   refused to save (cloud#972).
+ * - `0` — a number's identity element. "Zero hours logged" is data.
+ *
+ * An empty ARRAY *is* absent: the server has no array-valued scalar to
+ * disagree about, and "nothing picked" is a multiselect's own empty state,
+ * exactly as a blank string is a text input's.
+ */
+export function isMissingForRequired(value) {
+    return (value === undefined ||
+        value === null ||
+        (typeof value === 'string' && value.trim() === '') ||
+        (Array.isArray(value) && value.length === 0));
+}

package/dist/validation/schema-validator.d.ts

@@ -16,21 +16,37 @@
  */
 import type { BaseSchema } from '@object-ui/types';
 /**
- * Validation error details
+ * One issue found while walking an ObjectUI schema TREE — `path` locates the
+ * offending node (e.g. `children[0].type`), and `type` says whether it is fatal.
+ *
+ * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
+ * interface carried until objectstack#4115. That one describes PLUGIN-manifest
+ * validation and is keyed by `field`, with no severity discriminant. The two
+ * share no key beyond `message`/`code`.
+ *
+ * Naming convention for this family, set here and followed by the rest of the
+ * burn-down: `<what-is-validated>Validation<Error|Result>`. (`SchemaValidationResult`
+ * and `SchemaValidationReport` are themselves spec exports — checked, not assumed.)
  */
-export interface ValidationError {
+export interface SchemaNodeValidationError {
     path: string;
     message: string;
     type: 'error' | 'warning';
     code?: string;
 }
 /**
- * Validation result
+ * The outcome of validating an ObjectUI schema tree.
+ *
+ * NOT the spec's `ValidationResult` (`@objectstack/spec/kernel` and
+ * `@objectstack/spec/contracts`), whose name this interface carried until
+ * objectstack#4115: there `errors`/`warnings` are OPTIONAL arrays of
+ * `{ field, message, code? }` describing a plugin manifest. Here both arrays are
+ * required and carry node paths.
  */
-export interface ValidationResult {
+export interface SchemaNodeValidationResult {
     valid: boolean;
-    errors: ValidationError[];
-    warnings: ValidationError[];
+    errors: SchemaNodeValidationError[];
+    warnings: SchemaNodeValidationError[];
 }
 /**
  * Validate a complete schema
@@ -53,7 +69,7 @@ export interface ValidationResult {
  * }
  * ```
  */
-export declare function validateSchema(schema: any, path?: string): ValidationResult;
+export declare function validateSchema(schema: any, path?: string): SchemaNodeValidationResult;
 /**
  * Assert that a schema is valid, throwing an error if not
  *
@@ -91,4 +107,4 @@ export declare function isValidSchema(value: any): value is BaseSchema;
  * @param result - The validation result
  * @returns Formatted error summary
  */
-export declare function formatValidationErrors(result: ValidationResult): string;
+export declare function formatValidationErrors(result: SchemaNodeValidationResult): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "17.1.0",
+  "version": "17.2.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,11 +25,11 @@
     }
   },
   "dependencies": {
-    "@objectstack/formula": "^17.0.0-rc.0",
-    "@objectstack/spec": "^17.0.0-rc.0",
+    "@objectstack/formula": "^17.0.0-rc.1",
+    "@objectstack/spec": "^17.0.0-rc.1",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "17.1.0"
+    "@object-ui/types": "17.2.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",