vueda

Appearance

View Markdown

Glossary ​

Action ​

A named operation that a VUEDA viewset exposes. The built-in actions are list, retrieve, create, update, partial_update, and destroy. Any other action is an Extra Action. Model Info and object payloads report actions by these names. Client routes use the same names, except read, which maps to the Canonical Action Name retrieve.

Action Availability ​

Which actions the client offers a user. It draws them from Model Actions, each object's Available Actions, Permitted Transitions, and Valid Transitions, and the model config's routeActions and actions narrow them. The client uses these lists for routes and buttons. The server checks each request again when it runs.

Action Namespace ​

The unified client action identifier space that includes CRUDL/extra action names and workflow transition codes.

Action Redirect ​

The view an action form opens after its action succeeds or you cancel it. You set it per action in the model config's actionRedirects, with a default entry, and a returnPath query value takes precedence. The actionRedirect parameter of makeCRUDRoutes is a separate setting: where Route Admission sends a rejected route.

Action View Resolution ​

How ViewActionRouter picks the view component for a route that passed Route Admission. It renders ViewActionNotFound when neither Model Info nor the Permitted Transitions list the action. Otherwise it tries the built-in view registry, then a project view named by convention, then a generic view for the action or transition. A transition code skips the built-in registry.

Action-Scoped Expand ​

A per-action list of the relations a request to that action may Expand, set on the viewset as permit_<action>_expands. An action without one allows every declared expand, except list, which allows none until you set permit_list_expands. On list, retrieve, create, update, and partial_update, the server rejects a request that expands a relation that the action does not permit.

Auth-Scoped Stores ​

The client stores whose cached data depends on the signed-in user's permissions: Model Info, Model Config, workflow, and model choices. When a different user signs in or the user signs out, the client empties all four, and composables fetch again. A failed model info fetch, workflow fetch, or config build stays cached for its key until a user change, a store reset, or a page reload clears it.

Available Actions ​

The available_actions field on an object payload: the actions the current user may perform on that object. Each built-in action that the viewset implements, except create, appears when an Object-Scope Check passes; extra actions appear when get_allowed_extra_actions includes them. The server includes the field only when the request asks for it through Sparse Fields (f).

Baseline Permission ​

The decision that Django's model permission check makes for a codename without an object, from the user's own and group permissions. It never depends on an object's state or row. It is the first of the Permission Layers, and later layers can change it for one object. Superusers pass before this check runs.

Bulk Action ​

An Extra Action declared with bulk=True. VuedaRouter also mounts it at the list URL, so one request can target several objects.

Cancellable Promise ​

A promise with a cancel() method that aborts its HTTP request. fetchHelper and the default CRUD Adapter functions return one. Promises returned by store actions have no cancel().

Canonical Action Name ​

The name that Model Info uses for an action, which the client compares when it matches a route's action. The route segment read maps to the canonical name retrieve, and every other name maps to itself.

Canonical Registration ​

Registering a model with register or register_serializer, usually in AppConfig.ready(). It records the model's Canonical Serializer and, with register, its Canonical Viewset. Model Info describes only registered models.

Canonical Serializer ​

The serializer registered for a model. Its fields and Meta.expandable_fields define the field and expand sections of the model's Model Info.

Canonical Viewset ​

The viewset registered with a model's Canonical Serializer. Model Info reads the model's actions, filtering, and column totals from it. It also reads the orderable fields from the viewset's ordering_fields, and the default ordering from its ordering when it declares one.

Choice-Backed Field ​

A field or filter whose Model Info entry sets choices to a list or to true. A list of {label, value} pairs with string values is the complete set. The value true means the options are rows of another model or, for a filter, a column's current values, and the client loads them from the server when the field needs them.

Client Affordance ​

What the client shows or enables for a user, such as a visible action button or a route the guard admits. Affordances are client behavior; the server authorizes every request on its own.

Column Adapter ​

The component that renders the cells of one list column, such as ColumnText or ColumnModelLink. A field(<name>) slot replaces it; otherwise VUEDA picks it from the columnComponents prop, then the model config's columnComponents, then the field type's mapping, and finally ColumnText.

Column Totals ​

Per-column sums that a list response returns in columnTotals, computed over every row that the filters and Row-Level Permissions leave, across all pages. Only a paginated response carries them. A viewset declares them in column_totals, and a request names the ones it wants in the ct query parameter.

Composite Primary Key ​

A primary key made of several model fields, declared with Django's CompositePrimaryKey. VUEDA sends its value as a JSON array string, such as ["1", "42"], and reads that string from the pk segment of a detail URL.

Composition Primitive ​

An underscore-prefixed Theme Key, such as _ButtonBase, that styles no component on its own. A Theme Slot lists primitive slots in its composes array and takes their classes before its own. A change to one primitive reaches every slot that composes it.

Computed Field ​

A form field that always renders in FormField, outside the Form Context. It renders read-only unless fieldProps sets readOnly: false for it. You name computed fields in the model config's computedFields list or the form's computedFields prop, which replaces the list.

Content Type ​

Django's ContentType row, which identifies a model by its app_label and model name. VUEDA uses content types to identify the model behind model info, permissions, and workflows. They also identify the record that a queue item links to.

CRUD ​

VUEDA's five permission and action names: create, read, update, delete, and list. VUEDA adds list to each model's default permissions unless the model declares its own default_permissions. Codenames take the form <app_label>.<name>_<model_name>, such as vueda_vdq.list_queueitem. Client routes use these names. On the server, read covers every GET except list, update also covers partial_update, and delete covers destroy.

CRUD Adapter ​

A function that performs one data operation, such as retrieve, update, or delete, for the reactive-helpers list and object composables. The adapters cover list operations too: list, bulk delete, and actions on several objects. setupDefaultListCrud and setupDefaultObjectCrud register VUEDA's REST adapters, and you can replace any of them.

CRUD Routes ​

The two client routes that makeCRUDRoutes registers for every model and action. The detail route, /:app/:model/:action/:pk, targets one object; the list route, /:app/:model/:action/, targets a model or the objects in its pk query value. Either route may carry a returnPath query value, where an action view goes after it succeeds or the user cancels it.

CRUDL ​

create, read, update, delete, list permission/action vocabulary used by VUEDA.

CRUDL Routes ​

The two client routes that makeCRUDRoutes registers: a detail route at /:app/:model/:action/:pk for one object, and a list route at /:app/:model/:action/ that takes comma-separated primary keys as the pk query value for a bulk action. Either route may carry a returnPath query value, where an action view goes after it finishes.

CRUDL View Resolution ​

The client-side mechanism that maps each CRUDL action to a Vue component via setCrudComponents, with ViewActionRouter selecting the correct component at render time.

Customization Scope ​

How much of the UI one theming change reaches. The four scopes are instance (Theme Override), component (Theme Key), family (Composition Primitive), and brand (Theme Token). Pick the narrowest scope that covers your change.

Done State ​

A Queue Item workflow state that ends processing: cancelled, succeeded, or unconfirmed. The queue list hides items in a done state, and Sent Item endpoints show only them. errored is not a done state, so an errored item stays in the queue.

Dry Run ​

A request mode, set with the Dry-Run: true header, that validates a write and keeps none of its database changes. An extra action declared with VUEDA's action decorator runs its body, and the server then rolls back the database transaction. Work outside the database still runs. destroy runs its checks and deletes nothing. The other built-in writes ignore the header.

Expand ​

A request option that returns a related object inline in place of its primary key. You name relations in the e query parameter, choosing from the ones the serializer declares and Model Info lists. The action's Action-Scoped Expand list narrows that choice. On a write, a relation named in e also accepts a nested object, for a Nested Write.

Extra Action ​

An Action that a viewset declares with VUEDA's action decorator, in addition to the built-in actions. It targets one object when declared detail=True and the model otherwise; a Bulk Action can target several objects. Model info reports it by its url_name.

Fast Transition ​

A Transition that server code applies through fast_transition. It checks only that the current state is a source for the transition, skips permission checks, and records the change under the system user. From a source marked ignored, it keeps the state and runs on_transition_ignored; VDQ uses this for late provider callbacks.

Feature Policy ​

A VUEDA Model's per-feature settings, declared in a nested class Vueda with one inner class per feature, such as History or Workflow. Options a model leaves out take the feature app's defaults, and declarations inherit through the model's bases.

Field Path ​

The key that names one field in a form, with dots for nested objects and brackets for list items, such as address.city or items[0].quantity. The Form Context and the client's parsed server errors key fields by it.

Field Subset (fields) ​

Contract option to request a sparse response containing selected fields.

Form Context ​

The shared form state and methods that useForm provides to the fields inside a form: values, errors, messages, and touched and ignored fields. Each field calls useField, which creates a field context that reads and writes the form context at the field's Field Path.

Form Field ​

The component that renders one field's label, help text, and error and warning messages around its Widget. VUEDA picks it from the form's fieldComponents prop, then the model config's fieldComponents, then the default. The default is FormField, or an Inline for an expanded relation. A Computed Field always uses FormField.

Formatted Name ​

The display label each VUEDA Model exposes as formatted_name, which the client shows for related objects and choices. By default it is a stored generated column that copies the model's name field. A model can instead supply it through another expression, a lookup path, or a get_formatted_name() method.

Group Management Page ​

A page, served only when DEBUG is on, where you rename groups and add or remove the permissions each group holds. VUEDA records each change for a Group Permission Migration.

Group Permission Migration ​

A migration that makegroupmigrations writes from the changes recorded on the Group Management Page, so other environments receive the same group permissions. It names groups and permissions by natural key and goes in the app of AUTH_USER_MODEL.

Hairline ​

VUEDA's edge line for controls and surfaces. Its width comes from the --vueda-hairline-width token, which steps down as screen pixel density rises. The hairline utility paints it as an inset shadow, so a four-sided edge adds no layout width.

Icon Registry ​

The registry that maps icon names, such as loading or check, to Vue components, grouped by component name. It starts empty. You fill it with setIcons or patchIcons, for example by installing the Font Awesome Free preset.

Ignored Field ​

A Field Path marked with the form context's ignore method. The form leaves an ignored field out of the values it submits. In an object form, errors on an ignored path do not block submitting. An Inline ignores each saved row you mark for removal.

Inline ​

A field set that edits related objects inside the parent form. FieldSetTabularInline shows them as table rows and FieldSetStackedInline as stacked cards. Saving the parent sends them in a Nested Write.

Integrator ​

A team integrating VUEDA into a domain application.

List Scope ​

A constraint on a list that a link or your application code supplies, shown as a chip with no editable input. It comes from a hidden filter's value in the URL, or from a params key you declare in the scopes option.

Lookup ​

An abstract model base for reference tables of codes and names, such as statuses or categories. It provides a unique code, a name, and a Formatted Name. It is a VUEDA Model base.

Model Actions ​

The model_actions list in Model Info: the actions the model's viewset offers the current user, with no object in view. Built-in actions appear when a Model-Scope Check passes; extra actions appear when get_allowed_extra_actions includes them. The list shapes client routes and buttons, and each endpoint still enforces its own permissions.

Model API Path ​

The server path the client requests for a model's endpoints: /routes/<app_label>/<model_name>/, with detail and action paths below it. You serve each viewset there, or change the client's URL templates with setCustomUrl.

Model Config ​

The client's settings for a model's views, built from Model Info and the overrides you pass to setConfig. Overrides have a generic layer for every view and a per-view layer keyed by view name. For the same key, the per-view layer wins.

Model History ​

The record of inserts, updates, and deletes that VUEDA keeps for each tracked model, stored as pghistory event rows. VUEDA tracks every managed VUEDA Model unless its Feature Policy sets History.enabled = False. Event rows are append-only, and VUEDA sets no retention policy.

Model Info ​

The metadata the server publishes for each registered model, in seven sections: fields, actions, expands, ordering, filtering, column totals, and permissions. The actions section depends on the requesting user. The client builds its default views from model info and caches it per model.

Model-Scope Check ​

A permission check with no object, which asks whether the user may perform an action on the model at all. The server runs it before a request fetches any object, and it runs one for each built-in action to build Model Actions.

Model-Scope Deferral ​

On a Workflow-Enabled Model, the server can hold a model-scope denial open. It does so when a State Permission rule grants the codename to one of the user's groups. It applies only where a later object check or list filter decides the request; create keeps the denial. This is server enforcement.

Model-Scope vs Object-Scope Availability ​

The contract distinction where model_actions advertises model-level action availability and available_actions reports per-object availability.

Nested Write ​

A create or update that sends related objects inside the parent payload and saves them in the same request. A relation accepts nested objects when its serializer field is a nested serializer or the request names it in Expand.

Non-Field Error ​

A validation error or warning that belongs to the whole form, sent under the non_field_errors key. VUEDA's exception handler also puts a validation error raised as a list under that key. FormMessage renders these messages in the form.

Object State ​

The record that stores which workflow state one object is in. VUEDA creates it in the workflow's initial state when a save of a Workflow-Enabled Model object finds none. A raw save, such as a fixture load, creates none. backfillworkflowstates creates any that are missing.

Object-Scope Check ​

A permission check against one object, including its Row-Level Permissions and State Permission rules. The server runs it on requests for that object, and it decides which built-in actions appear in the object's Available Actions.

Permission Layers ​

The checks VUEDAPermissionsMixin.has_perm runs for a permission, in order: the Baseline Permission, State Permission rules, check_instance, and check_instance_workflow. Each layer that returns an answer replaces the decision so far, except that a state deny skips check_instance. Superusers pass before any layer runs; this is server enforcement.

Permission Mapping ​

The PERMISSION_NAMES_MAPPING setting, which maps Django's permission action names to VUEDA's. By default add becomes create, change becomes update, and view becomes read. It takes effect when your settings import vueda.core.patch_django after setting it.

Permissions and Workflow Overview ​

A read-only page, served only when DEBUG is on, that lists each registered model's permissions and the groups that hold them. It also lists each workflow's transitions, workflow permissions, and state rules, and can show what one selected user holds. You edit groups on the Group Management Page.

Permitted Transitions ​

The transitions of a model's Workflow that the current user may execute, computed at model scope with no object. The client uses them for Route Admission and for transition buttons on list views. Executing one still checks the object and its current state on the server.

Pk Marker ​

The pk: true flag that Model Info sets on the field whose name matches the model's primary key. The client reads it to find each object's identifier, and fails to load the model's metadata when no field carries it.

Public Name ​

The dotted path that a request uses for a field, filter, ordering term, or expand, such as customer.formatted_name. For ordering terms and declared filters, the server keeps the __-joined Django path internal, so a request names them by public name, never by ORM path.

Query Parameter Validation ​

The server's rejection of query parameters that a request does not recognize. A list or retrieve request rejects an unknown key. A list, retrieve, create, update, or partial_update request rejects an f or e value that the endpoint does not offer. Each rejection returns a validation error that names the parameter or value.

Queue Item ​

The database row for one VDQ (VUEDA Dispatch Queue) message to one receiver. It holds the sender, receiver, method (email or sms), and send result, and an Object State holds its workflow state. add_email creates one queue item per to, cc, and bcc address.

Queue Item (VDQ) ​

The persistent work record in VDQ that tracks one queued send operation, its workflow state, and processing metadata.

Reauthentication ​

A check that a signed-in user confirmed their identity recently. The account decides which confirmation counts: a code for a user with a two-factor device, the password otherwise. The server enforces the check on sensitive actions, such as two-factor device setup. In the client, requireRecentAuth and the auth views route the user to the reauthenticate page and back.

Resource ​

A domain surface implemented across model, serializer, viewset, routing, and client config/UI.

Route Admission ​

The client-side checks that a navigation must pass to open one of the CRUD Routes, in order: optional sign-in, action allowlist, optional group membership. The allowlist is the user's Model Actions, narrowed by routeActions, plus the user's permitted transition codes. A failed check redirects or cancels the navigation, and the server still authorizes every request on its own.

A link from one list column's cells to each row's update view, or to its read view when you cannot update the row. You turn it on by naming the column in the model config's detailLinkField. The row's Available Actions decide which view the link opens, if any.

Row-Level Hook Surface ​

The row-level extension points (check_queryset, check_instance, and workflow variants) where project policy can filter rows or override object decisions.

Row-Level Permissions ​

Project rules, declared in a model's inner RowLevelPermissions class, that limit which rows a user may act on. check_queryset filters list, bulk destroy, and the history events that a user sees about related rows; check_instance joins each object permission check. It is opt-in server enforcement, and Row-Level Workflow Permissions adds two hooks for workflow models.

Row-Level Workflow Permissions ​

The two row-level hooks that run only for a Workflow-Enabled Model. check_instance_workflow runs last in an object check and can override any earlier decision, a state deny included. check_queryset_workflow can narrow a list further but cannot restore rows that State Permission filtering removed.

Sent Item ​

A Queue Item in a Done State, served by its own endpoints for delivery history and resend. Resending a sent item creates a new queue item and schedules it.

Sent Item (VDQ) ​

The completed-history view of a VDQ queue record used for sent-item listing and resend operations.

Serializer-Only Registration ​

Registering a model with register_serializer and no viewset. The model gets field, expand, and permission metadata and its choices endpoints, and no actions, filtering, or column totals.

Server Feedback ​

Validation errors and Warning Confirmation warnings from the server, stored in the Form Context under the reserved server code. Local validation cannot write that code. A field's server feedback clears when the field blurs, and remaining server errors do not block the next submit.

Skin ​

The token-level look of VUEDA: color, type, spacing, radius, and density. A re-skin changes these values through Theme Token overrides and keeps each component's Visual Contract.

Sparse Fields ​

A request option that narrows a response to named fields. You list fields to keep in f and fields to drop in om; on a write, both shape only the response. f also requests fields that a response leaves out by default, such as Available Actions.

State Permission ​

A rule that grants or denies one permission codename to one group while an object is in one workflow state. On an object check, a grant overrides a Baseline Permission denial and a deny overrides a grant; when rules conflict, deny wins. List filtering applies the same rules to each row; this is server enforcement. Superusers pass before state rules run.

Theme Key ​

One entry in the Theme Registry, named after the component it styles (Button). A Composition Primitive key has an underscore prefix (_ButtonBase). Each theme key holds one or more Theme Slot entries.

Theme Override ​

A partial theme object, keyed by component name, that you pass through a component's themeOverride prop. useThemeOverride merges it with overrides from ancestors and provides the result to every descendant. It changes one subtree of the page.

Theme Registry ​

The active theme: a JavaScript object that maps each component name to its Theme Key entry. Each themed component adds its default entry with patchTheme when its code loads. setTheme replaces those defaults. Your project changes go in through overrideTheme, which keeps them in a separate store above the defaults, whatever order the two load in. clearThemeOverrides removes them.

Theme Slot ​

One named element of a Theme Key, such as root or thumb, that receives its own classes. Vue slots, which pass template content into a component, are a separate feature.

Theme Token ​

A CSS custom property defined in the default theme's base.css, such as --primary or --vueda-control-height. Theme classes read their values from tokens. Overriding a token after the base.css import changes every component that uses it.

Tone and Emphasis ​

The two design axes of a Button. Tone is the color role (neutral, primary, destructive); emphasis is the structure (fill, outline, ghost, link). Each pair maps to one button Composition Primitive.

Transition ​

A workflow operation that moves an object from one of its source states to a target state. Its code identifies it in API requests and client routes, and its name is display text.

Transition Permission ​

A row that names one permission a user must hold to execute one transition. The user must hold every permission that the rows name, checked against the object so that State Permission rules apply. A transition with no rows denies every user, superusers included; this is server enforcement.

Two-Factor Authentication ​

A second sign-in step that asks for a one-time code from an authenticator app, SMS, or email. VUEDA stores each method a user registers as a TOTPDevice. The server requires the code; the client routes to the 2fa page when the server asks for it.

Valid Transitions ​

The valid_transitions field on a workflow model's object payload: the transitions from the object's current state that pass the Workflow Permission and Transition Permission gates for that object. A source state marked ignored contributes no transitions. The field is empty when the user fails the workflow gate. The detail view reads it for its transition buttons.

VDQ (VUEDA Dispatch Queue) ​

VUEDA's Django app for queued outbound email and SMS. Each message to one receiver is a Queue Item with a workflow state. Celery workers send it, and provider callbacks or SMS polling record the delivery result.

View Field Lists ​

The three field lists a Model Config holds for each view. displayFields is what the view shows, fetchFields what it requests in f, and submitFields what a save sends. Model Info supplies their defaults.

Visual Contract ​

What a component page guarantees stays true after a re-skin: the component's variants, sizes, and states. Each page links the theme keys and theme tokens that set its current values.

VUEDA Model ​

A Django model that derives from FormattedNameBaseModel, usually through VUEDA's abstract model bases VuedaModel and Lookup. Only a VUEDA model carries a Formatted Name and a Feature Policy.

Warning Channel ​

The confirmation-gated path for advisory server warnings: a non-empty get_warnings() result withholds the write and returns 409 Conflict until the client resubmits with an acknowledged digest.

Warning Confirmation ​

The step that holds a write until the user confirms its advisory warnings. The server answers an unacknowledged write with 409 Conflict, the warnings, and a digest. The client resubmits with that digest in the Acknowledge-Warnings header.

Widget ​

The input control inside a Form Field, such as a text box or a select. VUEDA picks it from the form's widgetComponents prop, then the model config's widgetComponents, then the default type mapping, which mergeDefaultFieldMappings extends. A field that renders read-only uses its type's read-only widget and ignores those overrides. When the type has no read-only widget, the field uses WidgetReadOnly.

Wire Query Parameters ​

The short query parameter names that VUEDA endpoints read. f, e, and om shape the fields; s searches; o orders; p and ps paginate; ct requests column totals. Server settings define the names, and the client holds matching constants.

Workflow ​

The states, transitions, initial state, and permission rows defined for one model's Content Type; each model has at most one. You build workflows in the workflow management views and ship them to other environments as Workflow Migration files.

Workflow Migration ​

A Django migration that makeworkflowmigrations writes from the workflow changes recorded in history, so a workflow built in one database reaches other environments. It names records by code, app label, and model, since primary keys differ between databases.

Workflow Overlay ​

The effect of State Permission rules on a Workflow-Enabled Model. Object checks and list filtering grant or deny CRUD codenames by the object's workflow state. This is server enforcement.

Workflow Permission ​

A row that names one permission a user must hold to use a workflow's transitions. The user must hold every permission that the rows name, and a workflow with no rows denies every user, superusers included. Groups receive these permissions as ordinary Django group permissions; this is server enforcement.

Workflow-Enabled Model ​

A VUEDA Model whose Feature Policy enables workflow, with enabled = True in class Vueda.Workflow. It needs a Workflow definition. Without one, saving an object and every workflow request raise WorkflowNotConfiguredError, which the API returns as HTTP 500.