@praxisui/table 9.0.4-rc.48 → 9.0.4-rc.49

package/README.md

@@ -99,6 +99,40 @@ Use `resourcePath` when the host wants the table to enter backend schema/data mo
 
 `resourcePath` is enough only when the host already provides the Praxis API/CRUD wiring expected by the table runtime. In remote mode, the table derives columns from the backend schema contract and data from the backend resource/filter contract.
 
+For schema-governed tables that need only a few editorial differences, keep
+`columns: []` and declare a schema projection. The runtime derives every visible
+column from `/schemas/filtered` and reapplies the overrides by canonical field
+name whenever the schema changes:
+
+```ts
+const config: TableConfig = {
+  columns: [],
+  columnProjection: {
+    source: 'schema',
+    include: ['competencia', 'salarioBruto', 'salarioLiquido'],
+    overrides: {
+      salarioLiquido: { sticky: 'end', width: '160px' },
+    },
+  },
+};
+```
+
+An unknown override never creates a client-only column, and the override cannot
+change the canonical `field`. Use explicit `columns` only when the page really
+owns a complete local projection rather than schema-derived defaults.
+
+The table editor keeps the expanded columns only in memory. On apply/save and
+in `configChange`, it serializes the contract back to `include` plus the actual
+`overrides`. Computed or other genuinely client-owned columns are preserved in
+`columnProjection.additions`; an addition cannot shadow a canonical schema
+field. This round-trip prevents customization from turning the compact page
+contract back into a schema copy.
+
+`include` is an ordered allowlist. Omit it only when every field marked as table
+visible by the backend belongs in the experience. Prefer it for financial,
+personal, or otherwise sensitive resources so future schema fields are not
+published implicitly.
+
 Optional collection operations such as export are not implied by a base route. Expose them only when backend capabilities or HATEOAS links prove that the operation is available.
 
 When the collection response exposes `_links.create` or a collection `capabilities` snapshot with create support, `PraxisTable` can materialize the canonical `create` toolbar action without requiring each host screen to duplicate labels, disabled state, schema URLs, or submit URLs. If the host provides `surface.open`, the action opens the create form as a governed collection surface; otherwise the table emits `toolbarAction` with the enriched action metadata for the composed host to handle.