Praxis Files Upload Runtime
Use this skill for the canonical Angular upload component in @praxisui/files-upload. Treat it as the governed Praxis upload runtime, not as a local file input wrapper.
Source Audit
Before editing code or guidance, inspect:
projects/praxis-files-upload/AGENTS.mdprojects/praxis-files-upload/README.mdprojects/praxis-files-upload/docs/host-files-upload-integration.mdprojects/praxis-files-upload/src/public-api.tsprojects/praxis-files-upload/src/lib/components/files-upload/praxis-files-upload.component.tsprojects/praxis-files-upload/src/lib/types/**projects/praxis-files-upload/src/lib/models/index.tsprojects/praxis-files-upload/src/lib/validators/file-upload.validators.tsprojects/praxis-files-upload/src/lib/config/**- focused unit specs and
test-dev/e2e/*.playwright.spec.tswhen backend, rate-limit, conflict, drag proximity, or UI events change
If praxis-file-management source is available, audit its AGENTS and backend upload contract too. If it is not checked out locally, state that and rely on the files-upload docs/services/specs as the local contract evidence.
Canonical Boundary
@praxisui/files-upload owns:
- runtime upload strategies
direct,presign, andauto filesUploadId,componentInstanceId, andASYNC_CONFIG_STORAGEpersistencebaseUrlconsumption for canonical files API paths- UI state for selected/pending files, progress, errors, readiness, drag proximity, full/compact modes, and result actions
- client validators for accepted types, max file size, max files per bulk, and max bulk size
- config separation into
ui,limits,options,bulk,quotas,rateLimit,headers, andmessages - i18n through
providePraxisFilesUploadI18n - Settings Panel config editor and widget config editor
The host owns API origin, auth, tenant/user headers, storage policy, authorization, final file lifecycle, and product decisions about whether runtime customization is allowed.
Runtime Rules
- Require
baseUrlfor real uploads. Do not hide a missing base URL with a no-op upload path. - Use stable
filesUploadIdfor persisted or customizable surfaces. AddcomponentInstanceIdwhen the same upload appears multiple times on a route. - Use
strategy='auto'only when trying presign first and falling back to direct is an intentional product behavior. - Preserve canonical endpoints through the client: direct uses
baseUrl/upload, bulk usesbaseUrl/bulk, and presign discovery usesbaseUrl/upload/presign?filename=.... - Keep visual choices in
config.ui; keep client guards inconfig.limits; keep backend-facing upload options inconfig.options; keep execution policy inconfig.bulk. - Keep quota and rate-limit fields as user feedback policy. Backend quota/rate enforcement remains a backend contract.
- Emit lifecycle events instead of adding host-local polling:
uploadStart,uploadProgress,uploadSuccess,bulkComplete,error,rateLimited,readinessChange,pendingStateChange, andproximityChange. - Preserve accessibility state such as
aria-busy, error live regions, progress labels, and focusable pending-file controls.
Authoring Rules
- Use
PraxisFilesUploadConfigEditor,PraxisFilesUploadWidgetConfigEditor,ConfigService, anduseEffectiveUploadConfigwhere applicable. - Keep Settings Panel apply/save/reset/reopen aligned with runtime config consumption.
- Keep authoring text and user-facing messages on the i18n path or explicit host-provided
messages.errorsoverrides. - Do not create host-local config aliases for strategy, limits, headers, quota, or rate-limit behavior when
FilesUploadConfigalready has the canonical path. - Before introducing a new field, classify the gap as
ja-suportado-so-ux,ja-suportado-mal-nomeado-ou-mal-materializado,suportado-parcialmente, orlacuna-real-de-contrato.
Validation
Use the smallest reliable proof:
npm run build:praxis-files-upload- focused specs for component runtime, validators, config service, config editor, widget editor, error mapper, API client, and presigned uploader
test-dev/e2e/*.playwright.spec.tsfor backend contract, rate limit, conflict, fail-fast, manual selection, drag proximity, and UI event behavior- docs/playground validation when public docs or examples change
- AI registry validation when manifests, capabilities, or component docs change
Report exactly what was validated and what remained unvalidated.
Companion Skills
- Use
praxis-files-upload-backend-contractfor presign, direct/bulk endpoints, backend envelopes, quotas, rate limits, headers, and error codes. - Use
praxis-files-upload-form-fieldforpdx-material-files-upload, dynamic-form integration,valueMode, and ControlValueAccessor behavior. - Use
praxis-files-upload-ai-validationfor authoring manifests, AI adapters, registry projection, and assistant validation. - Use
praxis-authoring-editors,praxis-angular-i18n-governance,praxis-angular-docs-playgrounds,praxis-angular-public-api-governance, andpraxis-angular-validation-gateswhen the change touches those governed surfaces.