Praxis Files Upload Form Field
Use this skill for the form-field wrapper around the upload runtime. Treat pdx-material-files-upload as the canonical Dynamic Fields upload bridge when forms need operational uploads, not as a generic file picker.
Source Audit
Before editing code or guidance, inspect:
projects/praxis-files-upload/AGENTS.md
projects/praxis-files-upload/README.md
projects/praxis-files-upload/docs/host-files-upload-integration.md
projects/praxis-files-upload/src/lib/components/files-upload-field/pdx-files-upload-field.component.ts
projects/praxis-files-upload/src/lib/components/files-upload-field/pdx-files-upload-field.component.spec.ts
projects/praxis-files-upload/src/lib/components/files-upload/praxis-files-upload.component.ts
projects/praxis-dynamic-fields/** when metadata discovery or field catalog behavior changes
- dynamic-form, CRUD, docs, examples, or playground consumers that embed the upload field
Canonical Boundary
pdx-material-files-upload owns:
ControlValueAccessor integration for upload fields
valueMode output shapes: metadata, id, metadata[], and id[]
- compact shell UX for pending files, upload/cancel actions, more actions, hints, and errors
- delegation to hidden
praxis-files-upload for real upload execution
uploadSuccess, bulkComplete, and error outputs for host side effects
- accessibility for grouped field shell, pending file overlay, error live region, and disabled state
The runtime component still owns upload execution, presign/direct/bulk behavior, progress, rate-limit feedback, config persistence, and backend contract mapping.
Form Rules
- Pick
valueMode from the backend form contract. Do not switch from metadata to id values only to simplify host code.
- Use array modes when the form contract expects a stable array shape even for one file.
- Preserve uploaded metadata fields required by downstream forms, CRUD, audit, or document workflows.
- Keep client validation errors visible in the field shell while final file validation remains backend-owned.
- Avoid using the dynamic-fields lightweight
upload control when the workflow needs operational upload, presign, quotas, rate-limit feedback, or persisted upload config.
- Do not duplicate upload execution in form hosts. Let the wrapper delegate to
praxis-files-upload.
Integration Rules
- Pass
baseUrl and config through the wrapper into the runtime component.
- Keep disabled state aligned with the Angular form control, upload in-flight state, and missing
baseUrl.
- Preserve
pendingStateChange and proximity behavior through the wrapper when UI state matters.
- In CRUD or dynamic-form screens, keep upload field semantics in field metadata or canonical config, not in per-screen event hacks.
- Use
praxis-form-runtime-submit when upload field values affect dynamic-form submit payloads or local/transient field rules.
Validation
Use the smallest reliable proof:
pdx-files-upload-field.component.spec.ts
- runtime component specs for delegated upload behavior
- dynamic-fields metadata discovery/catalog specs when the wrapper registration changes
- dynamic-form or CRUD focused validation when submit payload shape changes
- files-upload E2Es for manual selection, UI events, and backend contract when wrapper behavior reaches real upload
Report exact valueMode assumptions and all skipped gates.
Companion Skills
- Use
praxis-files-upload-runtime for the underlying runtime behavior.
- Use
praxis-files-upload-backend-contract for HTTP/presign/quota/rate-limit contracts.
- Use
praxis-form-runtime-submit, praxis-dynamic-fields-editorial, and praxis-crud-runtime-openmodes when form metadata, dynamic field catalog, submit payload, or CRUD flows are affected.
1---2name: praxis-files-upload-form-field3description: Use when Codex must wire, audit, document, or author `pdx-material-files-upload` and dynamic-form file upload integration, including ControlValueAccessor behavior, `valueMode` shapes, `metadata` versus `id` form values, compact upload shell UX, hidden `praxis-files-upload` runtime delegation, validation errors, pending file state, upload side effects, accessibility, dynamic-fields metadata, CRUD/form consumers, docs, examples, or host form integration.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-files-upload-form-field6---78# Praxis Files Upload Form Field910Use this skill for the form-field wrapper around the upload runtime. Treat `pdx-material-files-upload` as the canonical Dynamic Fields upload bridge when forms need operational uploads, not as a generic file picker.1112## Source Audit1314Before editing code or guidance, inspect:1516- `projects/praxis-files-upload/AGENTS.md`17- `projects/praxis-files-upload/README.md`18- `projects/praxis-files-upload/docs/host-files-upload-integration.md`19- `projects/praxis-files-upload/src/lib/components/files-upload-field/pdx-files-upload-field.component.ts`20- `projects/praxis-files-upload/src/lib/components/files-upload-field/pdx-files-upload-field.component.spec.ts`21- `projects/praxis-files-upload/src/lib/components/files-upload/praxis-files-upload.component.ts`22- `projects/praxis-dynamic-fields/**` when metadata discovery or field catalog behavior changes23- dynamic-form, CRUD, docs, examples, or playground consumers that embed the upload field2425## Canonical Boundary2627`pdx-material-files-upload` owns:2829- `ControlValueAccessor` integration for upload fields30- `valueMode` output shapes: `metadata`, `id`, `metadata[]`, and `id[]`31- compact shell UX for pending files, upload/cancel actions, more actions, hints, and errors32- delegation to hidden `praxis-files-upload` for real upload execution33- `uploadSuccess`, `bulkComplete`, and `error` outputs for host side effects34- accessibility for grouped field shell, pending file overlay, error live region, and disabled state3536The runtime component still owns upload execution, presign/direct/bulk behavior, progress, rate-limit feedback, config persistence, and backend contract mapping.3738## Form Rules3940- Pick `valueMode` from the backend form contract. Do not switch from metadata to id values only to simplify host code.41- Use array modes when the form contract expects a stable array shape even for one file.42- Preserve uploaded metadata fields required by downstream forms, CRUD, audit, or document workflows.43- Keep client validation errors visible in the field shell while final file validation remains backend-owned.44- Avoid using the dynamic-fields lightweight `upload` control when the workflow needs operational upload, presign, quotas, rate-limit feedback, or persisted upload config.45- Do not duplicate upload execution in form hosts. Let the wrapper delegate to `praxis-files-upload`.4647## Integration Rules4849- Pass `baseUrl` and `config` through the wrapper into the runtime component.50- Keep disabled state aligned with the Angular form control, upload in-flight state, and missing `baseUrl`.51- Preserve `pendingStateChange` and proximity behavior through the wrapper when UI state matters.52- In CRUD or dynamic-form screens, keep upload field semantics in field metadata or canonical config, not in per-screen event hacks.53- Use `praxis-form-runtime-submit` when upload field values affect dynamic-form submit payloads or local/transient field rules.5455## Validation5657Use the smallest reliable proof:5859- `pdx-files-upload-field.component.spec.ts`60- runtime component specs for delegated upload behavior61- dynamic-fields metadata discovery/catalog specs when the wrapper registration changes62- dynamic-form or CRUD focused validation when submit payload shape changes63- files-upload E2Es for manual selection, UI events, and backend contract when wrapper behavior reaches real upload6465Report exact `valueMode` assumptions and all skipped gates.6667## Companion Skills6869- Use `praxis-files-upload-runtime` for the underlying runtime behavior.70- Use `praxis-files-upload-backend-contract` for HTTP/presign/quota/rate-limit contracts.71- Use `praxis-form-runtime-submit`, `praxis-dynamic-fields-editorial`, and `praxis-crud-runtime-openmodes` when form metadata, dynamic field catalog, submit payload, or CRUD flows are affected.