Field.*. Each constructor emits a
SnackBase storage definition plus the semantic metadata every surface switches
on: which renderer a value gets, which operands a filter may use against it, and
whether it can be sorted.
Unknown types raise at declaration rather than at schema sync. Which
ui.* primitive renders a type is decided by the type,
not by the surface, so a date is a date picker in a form, a table cell, and a
filter bar alike.
The registry
This table is generated fromserialize_registry() in
src/snackapp/fields/registry.py. It is not transcribed, so it cannot describe a
registry that has changed.
currency and full_name compile their operands against sub-paths
(value.amount, name.first). SnackBase’s filter validator allows a
JSON-typed column nothing but IS NULL / IS NOT NULL, so those expressions
parse and the backend rejects them until SnackBase gains JSON-path filtering.
Filtering inside a composite is a compile-level capability today, not a live
one — which is why a collection searched by name wants a text display field.Composite contracts
Four shapes are fixed by the registry, which validates them on the way in and on the way out. A value that does not match raisesValidationError rather than
reaching storage.
currency — {amount, code}
sum() over a JSON
column, so a number a board column or a dashboard has to total should be
Field.number, not Field.currency.
full_name — {first, last}
null; a value that is not an object raises.
address — {street1, street2, city, region, postcode, country}
null.
emails, phones, links — [{value, label, primary}]
value. Exactly one entry is primary: a second claim is
dropped, and a list that claims none gets it on the first entry.
Types
Field.text
unique becomes a unique index on the column.
Field.long_text
text, rendered as a textarea.
Field.rich_text
json and edited with TipTap. The value is a string of
HTML — what the editor emits and what the display sanitises and renders; an
object with an html key is accepted too. Not sortable: a document has no
order.
Field.number
sum() and avg() accept, which is what a board column total and
a dashboard aggregate need.
Field.currency
{amount, code}.
Field.percent
% suffix. Stored as the number, not as a fraction.
Field.rating
max above 10 raises.
Field.boolean
Field.date
ui.calendar places records on one of
these.
Field.datetime
Field.select
options, stored as text. The choices drive the editor, and
ui.kanban takes its columns from them when none are named.
Field.multi_select
options, stored as json. Not sortable: a set has no order.
Field.email
Field.emails
[{value, label, primary}].
Field.phone
Field.phones
[{value, label, primary}].
Field.url
Field.links
[{value, label, primary}].
Field.full_name
{first, last}.
Field.address
{street1, …}.
Field.json
is_empty and is_not_empty, because that
is all the backend can ask of a JSON column.
Field.array
Field.file
Field.files
json.
Field.relation
to collection. display names the field a chip shows;
without it the target’s label_field, then name, then title, then id is
used. on_delete is "restrict", "set_null", or "cascade".
A column of relations is expanded by the backend in one batched lookup, so a
hundred rows with an owner cost the row query plus one lookup.
Field.relation_many
to collection. A multi-relation is what a
ui.record(tabs=[{"field": ...}]) tab lists.
Field.user
on_delete="cascade" raises: deleting a person must not
delete their records. access="private" adds one of these as owner when the
collection does not declare it.
Computed fields
Field.computed
return_type is "text", "number", "boolean", or "datetime". It decides
the operand set (text or number) and the sortability: text, number,
boolean, and datetime sort; anything else does not.
The permitted functions are exactly:
date_diff and date_add take a string-literal unit: 'days', 'hours',
'minutes', 'seconds', 'months', or 'years'.
Declared view placeholders
A declared default view —views= on a collection — cannot name the caller or
the current month when it is written, so four placeholder values are substituted
where the filter is read: