Merge pull request #10 from IntentFile/spec/default-value-seeds-new-rows

spec: defaultValue seeds a new row, not only the column

Author: delchev

docs/public/logo.png

@@ -12,6 +12,7 @@ The quick lookup surface: one line and a minimal snippet per construct. For rule
 | [`entities`](/spec/entities) | tables + CRUD UI + a generated data layer & API |
 | [field / relation attributes](/spec/entities#fields) | uniqueness, layout, read-only, dropdown filtering, cascades |
 | [`pattern`](/spec/entities#fields) | an input-format regular expression enforced in the UI and server-side |
+| [`defaultValue`](/spec/entities#defaultvalue-field-defaults) | a field default: column default, satisfies `required`, and seeds a new row in the UI |
 | [`dependsOn`](/spec/relations) | link a dropdown to another, copy a value from the referenced record, or default a line from the open document header |
 | [`function`](/spec/entities#function-the-presentation-role) | an explicit presentation role (Document, Setting, ...) |
 | [`label`](/spec/entities#label-a-stored-display-name) | a stored, read-only display name for lookups |

docs/reference.md

@@ -37,7 +37,7 @@ fields:
 | `required` | NOT NULL; the generated required-value validation keys on this. A field that also carries a default (`defaultValue`, or `init` on a relation) is NOT demanded from the caller - the default satisfies it |
 | `length` | column length for string types |
 | `pattern` | an input-format regular expression the value must match (string / text fields only) |
-| `defaultValue` | column default |
+| `defaultValue` | the field's default: the column default, the reason a `required` field is not demanded from the caller, and the value a **new** row is seeded with in the UI (see [Field defaults](#defaultvalue-field-defaults)) |
 | `unique` | a UNIQUE constraint (e.g. a code or business key) |
 | `precision` / `scale` | override the decimal default (16, 2) |
 | `readOnly` | rendered read-only in the UI (e.g. a calculated total) |
@@ -85,6 +85,28 @@ By default the generated UI controls follow declaration order - all fields first
 
 Names match field / relation names (case-insensitive). A partial order is fine - any property not listed keeps its default position and is appended after the listed ones.
 
+## defaultValue — field defaults
+
+`defaultValue` states what a field holds when nobody supplies a value:
+
+```yaml
+fields:
+  - { name: hours,    type: decimal, required: true, defaultValue: 8 }
+  - { name: billable, type: boolean, defaultValue: true }
+```
+
+It has three effects at once, which are deliberately one key rather than three:
+
+- it is the **column default**, so a row inserted without the column gets it;
+- it **satisfies `required`**, so the caller is not asked for a value the model already guarantees;
+- it **seeds a new row in the UI**, so an editor opens on the default instead of on a blank.
+
+::: info Normative
+A generator MUST apply the default when creating a new record and MUST NOT re-apply it to an existing one: a value the user cleared is a value the user chose, and re-defaulting it on the next edit would silently undo an intentional change. The default is a *starting value*, not a constraint — the user may replace it, and nothing revalidates a stored row against it. On a to-one relation the equivalent key is [`init`](/spec/relations), which names a seeded record.
+:::
+
+A default is what makes a bulk affordance one action rather than several: a dialog that creates one line per working day is only useful if the line it creates already carries the usual values.
+
 ## Calculated fields
 
 A field value can be derived instead of entered: