@object-ui/plugin-tree 17.6.0 → 18.0.0

package/README.md

@@ -7,44 +7,177 @@ the right view for hierarchies of unbounded depth such as **business unit /
 org chart**, category trees, menu trees, BOMs, or nested comments. (Grouping
 handles *fixed-depth* hierarchies; a tree handles arbitrary depth.)
 
-It registers two component types via the `ComponentRegistry`:
+It registers one component type via the `ComponentRegistry`:
 
-- `object-tree` — the object-bound renderer
-- `tree` — the view-type alias used by `ObjectView` / `ViewSwitcher`
+- `object-tree` — the object-bound renderer, and the one an author selects
+
+The bare `tree` registry key (`view:tree`), a second key on the same renderer,
+is RETIRED (objectui#10859 batch 8): `objectui validate` refused it at `type`,
+and nothing authored it. `tree` survives as a host-composition VIEW type (see
+below), which `ObjectView` and `ListView` compose into an `object-tree` node.
 
 ## Usage
 
+Author an `object-tree` node. `ObjectQLComponentSchema` narrows on `type`, so
+each key is checked against `ObjectTreeSchema`, which mirrors the `object-tree`
+row of `@objectstack/spec` (17.5.0 and later):
+
 ```ts
-// As a view inside an ObjectView
-{
-  type: 'object-view',
+import type { ObjectQLComponentSchema } from '@object-ui/types';
+
+const schema: ObjectQLComponentSchema = {
+  type: 'object-tree',
   objectName: 'business_unit',
-  views: [
-    {
-      type: 'tree',
-      tree: {
-        parentField: 'parent',        // single-parent pointer (auto-detected if omitted)
-        labelField: 'name',           // indented first column
-        fields: ['name', 'manager'],  // additional flat columns
-        defaultExpandedDepth: 1,      // 0 = roots only; omit = expand all
-      },
-    },
-  ],
-}
+  tree: {
+    parentField: 'parent',        // single-parent pointer (auto-detected if omitted)
+    labelField: 'name',           // indented first column
+    fields: ['manager'],          // additional flat columns
+    defaultExpandedDepth: 1,      // 0 = roots only; omit = expand all
+  },
+  filter: [{ field: 'status', operator: 'equals', value: 'active' }],
+  navigation: { mode: 'drawer' },
+};
 ```
 
-### Config
+### Keys
+
+| Key | Description |
+| --- | --- |
+| `objectName` | The object to query. One of `data`, `staticData` and `objectName` is the record source, read in that order; `objectui validate` refuses a node with none of the three. |
+| `data` | A `{ provider, … }` configuration, read first. `{ provider: 'value', items }` draws those records and `{ provider: 'object', object }` queries that object. The `api` and `schema` providers draw no rows on the tree. A bare array is not a record source (objectui#8348): inline rows go under `staticData`. |
+| `staticData` | Inline records, read second: a `data` configuration wins, and a tree carrying both `staticData` and `objectName` draws these rows and never queries the object. |
+| `tree` | The field configuration — the spec's `TreeConfig` (table below). |
+| `filter` | Rule array `[{ field, operator, value }]`, lowered to `$filter` and applied to inline rows as well. Context tokens such as `{current_user_id}` are resolved first. A record whose parent the filter removed is drawn as a root. |
+| `navigation` | What a row click opens (below). |
+
+The node's `dataSource` binding is **not** a record source on this block: the
+registration is not wrapped in `ElementDataSourceGate`, so nothing lands a
+binding's object on `objectName`, and `objectui validate` does not count it.
+
+### The `tree` block
 
 | Key | Default | Description |
 | --- | --- | --- |
 | `parentField` | auto-detected | Field holding the parent reference. When omitted, the renderer picks the object's `tree` field (or a lookup/master_detail that references the same object). |
 | `labelField` | `name` | Field rendered indented in the first column. |
-| `fields` | `[]` | Additional fields rendered as flat columns. |
+| `fields` | `[]` | Additional fields rendered as flat columns after the label. |
 | `defaultExpandedDepth` | _unset_ | Initial expansion depth. `0` = roots only; unset = expand everything. |
 
 Records whose parent is missing (or points outside the result set) are kept as
 roots, so nothing is silently dropped.
 
+⚠️ The same four keys written **flat** on the node are still read, and a flat
+key outranks the block's member of the same name. They are the form a host
+composes; the spec row declares only the `tree` block, so author that.
+
+### `navigation`
+
+`navigation` takes the spec's `NavigationConfig` (`{ mode, size, width,
+openNewTab, preventNavigation }`), the block a list view declares. On a tree no
+parent view navigates for:
+
+- **Absent**: a click opens nothing. This renderer supplies no drawer default.
+- `drawer`, `modal` and `popover` open the row's record in that overlay; `split`
+  opens it beside the tree, which stays drawn.
+- `new_window` opens `/{objectName}/record/{id}` in a new tab; `none` opens
+  nothing.
+- `page`, and a block without `mode` (it takes the spec's `page` default), open
+  a record page through the record navigator the host publishes (the console
+  publishes one on its custom pages, record pages and list views). The object
+  is `data.object` when `data` is the object provider, so it wins when both
+  are written, and the tree's `objectName` otherwise. Under a host that
+  publishes none, such as an embedded renderer, or on a tree that names neither
+  (inline rows with no `objectName`), there is no record page to open and the
+  click opens nothing.
+- `preventNavigation: true` opens nothing whatever the mode. `openNewTab: true`
+  opens the record page in a new tab and outranks every mode except `none`.
+- `size` picks the overlay width bucket; the deprecated `width` wins over it.
+
+A click handler from a parent view outranks the whole key.
+
+### Expansion: the seed and the user's answer
+
+`defaultExpandedDepth` **seeds** expansion; it does not own it. The seeded set is
+derived from the forest during render rather than mirrored into component state,
+so a tree that expands by default is painted expanded in the first commit that
+has rows — there is no frame in which the forest is drawn collapsed
+(objectui#8666).
+
+When the record set changes — a refetch, a filter, a host that reallocates the
+rows — the seed is recomputed for the new forest. A node the user opened or
+closed by clicking its chevron, **and which is still in the forest**, keeps the
+user's answer; every other node, a genuinely new one included, takes the seed.
+Expansion is per-mount session state: it is not addressable and is not persisted.
+
+### The `tree` view type is host composition, not authoring
+
+`tree` is **not** an authorable view type. Neither `ObjectViewSchema.defaultViewType`
+nor `NamedListView.type` admits it — both are the same seven-value union that stops
+at `map` — so no authored document selects a tree view, and `ObjectViewSchema`
+declares no `views` member at all. The `tree` branch runs only when a **host**
+composes `ObjectView` with a `views` prop, whose entries carry `id` and `label`
+and are typed `ViewType`. That was ruled deliberate on objectui#5321
+(2026-08-20): `tree` and `chart` are recorded as host-composition-only surfaces
+rather than added to the authored unions.
+
+The live consumer is the console: it passes stored view records to `ObjectView`
+as `views`, and its create-view dialog offers `tree` among the types a console
+user can create. To render a tree from authored metadata, write the
+`object-tree` node above.
+
+#### The host config has a type — `TreeViewConfig`
+
+Host config is **not** untyped config. A block a host stores and re-writes is a
+contract, so the per-view `tree` block is exported from `@object-ui/types` and
+the renderer imports it rather than keeping a private copy (objectui#8253,
+ruled 2026-09-07).
+
+⚠️ It is **not the single declaration of that shape**, and saying so was itself
+the defect objectui#8841 fixed. `@objectstack/spec` owns this block — it
+declares it as `TreeConfig` and hangs it on `ListView.tree` — and
+`@object-ui/types` already publishes it a second way, derived, as
+`ListViewSchema['tree']`. `TreeViewConfig` is now a **derivation of the
+protocol's block** rather than a copy of it — in `packages/types/src/views.ts`
+it is a one-line alias of `NonNullable<ListView['tree']>`, taken from
+`@objectstack/spec/ui`. So the accurate claim is the narrower one: this is the
+name a host writes against, and it tracks the protocol by construction rather
+than by anyone remembering to update it.
+
+```ts
+import type { TreeViewConfig } from '@object-ui/types';
+
+// The block a host writes as `tree` on a `views` entry, or as `options.tree`
+// on a stored view record. Every key is optional; a host writes the subset it
+// means.
+const treeConfig: TreeViewConfig = {
+  parentField: 'parent',        // single-parent pointer (auto-detected if omitted)
+  labelField: 'name',           // indented first column
+  fields: ['name', 'manager'],  // additional flat columns
+  defaultExpandedDepth: 1,      // 0 = roots only; omit = expand all
+};
+```
+
+Annotating the block is what turns a typo into a diagnostic: `parentFeild` used
+to be stored, read by nobody and reported by nothing, because the `views` entry
+admits any key. Against this type it is a compile error.
+
+⛔ `titleField` is **not** part of this block. objectui#8253 declared it as a
+legacy second rung for `labelField`; `@objectstack/spec@17.4.0` refuses
+`tree.titleField` by name (`TreeConfigSchema` is strict since spec #15469), so
+declaring it published a key the protocol rejects — an author who followed this
+type was refused at publish. objectui#8841 removed it.
+
+The renderers still *tolerate* a `titleField` already stored on a view record:
+`plugin-view`, `plugin-list` and the console's own composition each fall back to
+it when `labelField` is absent, so nothing that renders today stops rendering.
+Those reads are untyped tolerance awaiting a follow-up, ⛔ not a declaration —
+write `labelField`, which is the protocol's spelling and wins wherever both are
+present.
+
+⛔ This does not make `tree` an authorable view type. objectui#5321 is
+unchanged: the block is written by a **host**, never by a document author, and
+the authored node is the `object-tree` schema at the top of this file.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/ObjectTree.d.ts

@@ -1,10 +1,52 @@
 import { default as React } from 'react';
-import { DataSource } from '@object-ui/types';
+import { DataSource, ObjectTreeSchema } from '@object-ui/types';
 export interface ObjectTreeProps {
-    schema: any;
+    /**
+     * The `object-tree` node this renderer draws.
+     *
+     * Both of this package's registrations (`object-tree` and `tree`, in this
+     * package's `index.tsx`) publish one `treeInputs` list and one renderer, so one
+     * props type covers both tags — the shape `plugin-map` already has under two
+     * tags, and the shape objectui#8651 gave `ObjectCalendar`.
+     *
+     * ## What typing this BUYS, stated rather than assumed (objectui#8655)
+     *
+     * It was `any`, and an `any` is not a weaker answer than a type — it is NO
+     * answer. `checker.getPropertyOfType` through `any` returns `undefined` for
+     * `objectName`, which this schema certainly declares, exactly as it does for a
+     * nonsense token; so every "is this key declared?" asked of this prop came back
+     * "unknown" while LOOKING like "undeclared". That ordering is the card's — type
+     * FIRST, classify second — and it is objectui#8410's standing ruling that an
+     * absence returned by an instrument structurally unable to see a declaration is
+     * not a reading at all.
+     *
+     * ## ⚠️ The CEILING, so nobody reads this as more than it is
+     *
+     * `BaseSchema` ended in `[key: string]: any` when this was written, so an
+     * UNDECLARED key read off this type still compiled and typed `any`. What the
+     * annotation bought was that the question became ANSWERABLE by the checker, ⛔ not
+     * that an undeclared read was refused — the same ceiling objectui#5155 /
+     * objectui#7927 recorded for the mirror. objectui#8347 removed the signature, so
+     * an undeclared read off this type no longer compiles.
+     */
+    schema: ObjectTreeSchema;
     dataSource?: DataSource;
     className?: string;
-    onRowClick?: (record: any) => void;
+    /**
+     * TWO parameters since objectui#9357, and the second is not decoration: this
+     * prop reaches `useNavigationOverlay` as its `onRowClick`, and `handleClick`
+     * invokes it as `onRowClick(record, event)` — the modifier payload a host
+     * needs to implement Cmd/Ctrl/middle-click for itself. Declaring one
+     * parameter hid the second on the ONE line a host reads. Spelled `any` and
+     * not `HandleClickModifiers` for the reason objectui#9341 measured on
+     * `ObjectKanbanSchema.onCardClick`: that interface lives in
+     * `@object-ui/react`, the published twins in `@object-ui/types` may not name
+     * it, and a host that discovered the payload from the implementation
+     * annotated it `React.MouseEvent` — which a narrower declaration refuses
+     * contravariantly. `BaseSchema`'s own `onClick` / `onChange` / `onSubmit`
+     * already use this spelling for exactly this situation.
+     */
+    onRowClick?: (record: any, event?: any) => void;
     /** Inline data (passed by ListView/ObjectView for non-grid views). */
     data?: any[];
     loading?: boolean;

package/dist/ObjectTree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectTree.d.ts","sourceRoot":"","sources":["../src/ObjectTree.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,KAAuC,MAAM,OAAO,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,kBAAkB,CAAC;AA+B7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,GAAG,CAAC;IACZ,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACnC,sEAAsE;IACtE,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6KD,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAgRhD,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"ObjectTree.d.ts","sourceRoot":"","sources":["../src/ObjectTree.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,KAAuC,MAAM,OAAO,CAAC;AAC5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAkB,MAAM,kBAAkB,CAAC;AA4ErF,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAChD,sEAAsE;IACtE,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAggBD,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAwtBhD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,32 @@
 import { default as React } from 'react';
-import { ObjectTree, ObjectTreeProps } from './ObjectTree';
+import { ObjectTree, ObjectTreeProps } from './ObjectTree.js';
 export { ObjectTree };
 export type { ObjectTreeProps };
 export declare const ObjectTreeRenderer: React.FC<any>;
+/**
+ * ⛔ The bare `tree` node type key is RETIRED (objectui#10859 batch 8, the
+ * seat's ruling on that card, by the objectui#10393 / objectui#8760 route).
+ * `object-tree` is the one spelling this plugin serves.
+ *
+ * ## What was here, and why it went
+ *
+ * `ComponentRegistry.register('tree', ObjectTreeRenderer, { namespace: 'view',
+ * ... })` — a second key on the SAME renderer with the SAME `inputs`, which
+ * stored both `view:tree` and the bare `tree` fallback. Only `object-tree` has
+ * a declaration: `@objectstack/spec`'s `ComponentPropsMap` row, which
+ * `AnyComponentSchema` arms, while no arm claims `tree`. So `objectui validate`
+ * refused a node authored `type: 'tree'` at `type` while the registry mounted
+ * it. `PUBLIC_BLOCKS` already declined to curate it as "a second spelling of
+ * this one block".
+ *
+ * ## Why unregistering is the whole retirement
+ *
+ * Nothing wrote the node: 0 producers in source, docs, examples or the
+ * catalog, measured for the card. The other `tree` spellings in the stack are
+ * different layers and stay untouched — the FIELD type `tree` (a self-reference
+ * that `@object-ui/fields` renders as `field:lookup`) and a STORED list-view
+ * type, which `@object-ui/plugin-list`'s `ListView` already composes into an
+ * `object-tree` node. The console's lazy `tree` stub (`apps/console/src/register-plugins.ts`)
+ * went in the same change, so no host keeps the key alive.
+ */
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,CAAC;AAIhC,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,CAG5C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,CAAC;AAIhC,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,CAG5C,CAAC;AA+DF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}