@lotics/cli 0.321.125 → 0.321.126
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/cli.js +97 -115
- package/dist/src/client.d.ts +2 -0
- package/docs/agent_surface.md +2 -1
- package/docs/app_architecture.md +3 -3
- package/docs/build.md +40 -32
- package/docs/cli_reference.md +2 -2
- package/docs/data_model.md +8 -1
- package/docs/design.md +91 -73
- package/docs/document_templates.md +13 -11
- package/docs/examples.md +429 -252
- package/docs/filters.md +2 -0
- package/docs/getting_started.md +3 -3
- package/docs/workflow_steps.md +2 -0
- package/docs/workflows.md +13 -9
- package/docs/working_in_a_workspace.md +1 -1
- package/package.json +3 -1
package/docs/design.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
An app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The
|
|
4
4
|
tree states COMPOSITION — which fields, lists and acts each job's screen holds; how each piece looks is the platform's,
|
|
5
5
|
one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
|
|
6
|
-
write rules): a List's Readings band, the stage buttons, the picture. What a write stores, and the Section that follows the table: `reference/changing-an-app`. State a node to change it,
|
|
6
|
+
write rules): a List's Readings band, the stage buttons, the picture. What a table's `records` states of a row is its face, and every app that links to the table reads it. What a write stores, and the Section that follows the table: `reference/changing-an-app`. State a node to change it,
|
|
7
7
|
or `false` at it to turn it off (`"readings": false`, a Record's `"row": { "image": false }`). A field is written where its Record declares it: a Section's Field, the table's face (title, line, picture, figure), or every field where the Record states no Section; the head, a line, a column or a board draws it, and never makes one written; every head part (`row.title`, each `row.subtitle` entry, `row.figure`, `row.image`) takes `edit: false` to be read. A drawn Field is a control unless it
|
|
8
8
|
or its entity is read-only (`edit: false`); a stepped status is not, since Acts move it, unless its `row` states `status: { edit: true }`. Which apps a business needs is `app_architecture`.
|
|
9
9
|
|
|
@@ -15,38 +15,37 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
15
15
|
- What needs attention leads the row as an issue its table declares (`design/issues`): a derived flag is an issue, in the
|
|
16
16
|
warning tone on the row's line (in the danger tone where a Check's `on` refuses an act the row offers); every other yes
|
|
17
17
|
reads in the success tone. `records.mark` is a category's own mark, a select whose options carry a brand or glyph.
|
|
18
|
-
- A list's columns: the name and its lead, the
|
|
19
|
-
fact once: a column the row draws itself stands once. A generated number (`autonumber`)
|
|
20
|
-
the row's name to the subtitle's first part and stands first on its line. A row listed under its record is named by its
|
|
18
|
+
- A list's columns: the name and its lead, the stage, deadline and figure it draws unasked (a Record's `row` leaves one out), then the columns the job reads on every row, as many as fit a desk. Each
|
|
19
|
+
fact once: a column the row draws itself stands once. A generated number (`autonumber`) continues from the highest issued, or from the field's `next`
|
|
20
|
+
where its numbers are already past that; as the title it yields the row's name to the subtitle's first part and stands first on its line. A row listed under its record is named by its
|
|
21
21
|
subtitle's first part where its title only reads that record (a join row's lookup through the link back, or a link to a row of its own whose title is that record): title a join row by one side, its subtitle the other.
|
|
22
22
|
- A list worked by a date states `sort` on that date's column, newest first; without one, a register reads newest made
|
|
23
|
-
first
|
|
24
|
-
- Someone is a face wherever
|
|
25
|
-
field
|
|
26
|
-
`{"kind": "avatar", "name": "person"}`,
|
|
23
|
+
first, a record's child List in the order its rows were added.
|
|
24
|
+
- Someone is a face wherever read: a link to a table stating `records.party` draws its row's face, as a member
|
|
25
|
+
field does; select options naming people or organisations who are neither each take the `mark`
|
|
26
|
+
`{"kind": "avatar", "name": "person"}`, not a colour dot, so a person reads as a person.
|
|
27
27
|
- Each record is whole within its app: its page holds what the record is (its facts and its papers) and its child
|
|
28
28
|
rows, in parts a person moves between, so someone arriving at it understands it without guessing. Rows of another
|
|
29
29
|
app's job read in place as read-only lines — their name and figures — and the app states no page for an entity
|
|
30
|
-
another app works. A register opens on its rows with the figures its job reads
|
|
30
|
+
another app works. A register opens on its rows with the figures its job reads; a filter leaving one hides that the rest exist.
|
|
31
31
|
Completeness is of the work, never of decoration: a part, column or Reading nobody's work reads stays out.
|
|
32
|
-
- A thing shows its picture, a file its preview,
|
|
33
|
-
a chart, a register its Readings
|
|
32
|
+
- A thing shows its picture, a file its preview, planned work its days on a time axis, things kept at places the floor they stand on (a plan), a quantity a meter (`records.limits`) or
|
|
33
|
+
a chart, a register its Readings; long text reads whole (a markdown Field; `block: true` on plain long text).
|
|
34
34
|
- A number a reader judges — against a target or a bound, over time, as a mix of parts, through steps — is drawn as a
|
|
35
35
|
picture wherever it stands: a list's columns, a record, a card, a band. A Reading stands in each of those places, and
|
|
36
36
|
which picture each shape of Reading draws is `reference/reading-node`.
|
|
37
37
|
- An option with a `color` draws its dot where its select is drawn; one without reads as its word. A `mark` where a
|
|
38
38
|
brand or glyph names the option, on every option of a select read down a column (how it was paid, the channel).
|
|
39
|
-
- Every app states its tile's `color` and `icon`,
|
|
40
|
-
app stating no icon draws the one glyph every such app shares.
|
|
39
|
+
- Every app states its tile's `color` and `icon`, apart from the workspace's other apps.
|
|
41
40
|
- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
|
|
42
41
|
carrier, the authority) in the Section where that work happens, and the source of a
|
|
43
42
|
figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere. A paper a counterparty
|
|
44
43
|
sends (a supplier's invoice, a delivery receipt) is added on the record it arrives with — the order it is for — and
|
|
45
|
-
listed again where it is settled,
|
|
44
|
+
listed again where it is settled, since the counterparty's ledger alone hides it from the order.
|
|
46
45
|
|
|
47
46
|
<!-- generated:start words -->
|
|
48
47
|
|
|
49
|
-
**The words most builds state.** A node's page holds
|
|
48
|
+
**The words most builds state.** A node's page holds every other word: `reference/list-node`, `reference/records`, `reference/field`.
|
|
50
49
|
|
|
51
50
|
**Table**
|
|
52
51
|
|
|
@@ -107,6 +106,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
107
106
|
- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)
|
|
108
107
|
- `status` (Status): The stage a row moves through, a single select, drawn in the record's head, or its Side where the Side states it
|
|
109
108
|
- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)
|
|
109
|
+
- `tells` (map of alias → (`true` | `"field"` | `"link.field"` | `{ "group": id }`)): Members find out in their inbox that a deadline of `due` is three days off and again when it has passed, one card per member counting its rows
|
|
110
110
|
- `image` (alias | list of alias (at least one)): A files field that pictures the row, or a one-row link to a table with a picture (or a lookup of one through a one-row link: a delivery led by its order's customer), whose picture the row leads with
|
|
111
111
|
- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)
|
|
112
112
|
- `limits` (map of alias → (alias | number)): A number read against a bound
|
|
@@ -116,7 +116,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
116
116
|
|
|
117
117
|
**`records.status`**
|
|
118
118
|
|
|
119
|
-
- `field` (alias, required): The single select that is the row's state, its options in the order the work goes through them
|
|
119
|
+
- `field` (alias, required): The single select that is the row's state, its options in the order the work goes through them
|
|
120
120
|
- `closed` (list of alias (at least one)): Options that end the work
|
|
121
121
|
- `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)
|
|
122
122
|
- `dates` (map of alias → alias): Option alias → a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it
|
|
@@ -134,7 +134,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
134
134
|
|
|
135
135
|
- `entity` (alias, required): The table whose rows the List draws
|
|
136
136
|
- `create` (boolean | list of alias (at least one)): The fields an add asks
|
|
137
|
-
- `columns` (list of (alias | Edit column | Reading)): Fields read after the row's title, in this order, each drawn though no row holds it
|
|
137
|
+
- `columns` (list of (alias | Edit column | Reading)): Fields read after the row's title, in this order, each drawn though no row holds it, and one the `records` line also names leaves that line
|
|
138
138
|
- `label` (text): The register's name in the app's lists and tab strip
|
|
139
139
|
- `filters` (list of (alias | Tiered filter | Listed filter)): Fields the reader narrows by every day, beside the stage chips
|
|
140
140
|
- `children` (list of (Tab | Reading | Act | List) (at least one)): Its Tabs, band Readings and Acts over ticked rows or every row in view
|
|
@@ -151,7 +151,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
151
151
|
**Record**
|
|
152
152
|
|
|
153
153
|
- `entity` (alias, required): The table whose rows open on this page
|
|
154
|
-
- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path), and the Fields, Fieldsets, Lists, Readings, Statements and Comments stated directly
|
|
154
|
+
- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Tab in a Record | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps, bare or holding the Sections that are its path), and the Fields, Fieldsets, Lists, Readings, Statements and Comments stated directly
|
|
155
155
|
- `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App
|
|
156
156
|
- `row` (Record row): How the App reads this entity's rows wherever it lists them
|
|
157
157
|
- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer
|
|
@@ -195,7 +195,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
195
195
|
**Reading**
|
|
196
196
|
|
|
197
197
|
- `label` (text): What the figure is called
|
|
198
|
-
- `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one
|
|
198
|
+
- `value` (alias | `{ "avg": alias }`): A number field summed over the rows (absent, the rows are counted), or `{ avg }` averaged over the rows holding one
|
|
199
199
|
- `by` (alias | Tiered filter): Splits the rows into parts
|
|
200
200
|
- `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date's `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)
|
|
201
201
|
- `entity` (alias): The List's rows
|
|
@@ -206,35 +206,38 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
|
|
|
206
206
|
## Issues
|
|
207
207
|
|
|
208
208
|
A row takes what the person has, in the order it arrives — a supplier's paper after the delivery, a payment before its
|
|
209
|
-
invoice, a price filled in later. What is missing or out of order is an issue on the row,
|
|
209
|
+
invoice, a price filled in later. What is missing or out of order is by default an issue on the row, not a refusal;
|
|
210
210
|
refusal is kept for what must never happen and for the step that cannot be taken without a fact, which names it (an
|
|
211
211
|
invoice made without the buyer's tax code).
|
|
212
212
|
|
|
213
213
|
Whatever goes wrong on a row and needs a person to act — a line delivered short, a price missing, a customer over their
|
|
214
214
|
credit limit, a permit about to expire — is an issue its table declares in `records.issues`. A declared issue stands in
|
|
215
|
-
every app that draws its row
|
|
215
|
+
every app that draws its row: first on the row's line (`+N` the others), in the record's callout (a count of child rows as pills on those rows), in the List's filter of what needs checking with how many rows hold it, and those rows first. It never makes an
|
|
216
216
|
app draw a row it did not, and never shows on an `Outside` page. What needs no one's action is no issue: a stage is the
|
|
217
|
-
status, a category a select. A record's callout says each issue by its label and what it means: a text issue's own sentence, a yes/no issue's field `description` — give a yes/no issue's field one, or its line shows the name alone.
|
|
217
|
+
status, a category a select. A deadline in `records.due` already marks its row late and is counted; no issue, Check or Reading says it again. A record's callout says each issue by its label and what it means: a text issue's own sentence, a yes/no issue's field `description` — give a yes/no issue's field one, or its line shows the name alone.
|
|
218
218
|
|
|
219
|
-
|
|
220
|
-
|
|
219
|
+
|
|
220
|
+
An issue is a promise that someone will act every time it stands.
|
|
221
|
+
Declare an issue where each flagged case needs someone to act, since a rule that flags rows nobody fixes trains everyone
|
|
222
|
+
to ignore the colour; name those you assumed in the handover. Where a flagged row may be accepted as it is (a price agreed by
|
|
221
223
|
exception), give the acceptance a field the formula reads, so accepting it clears the issue.
|
|
222
224
|
|
|
223
225
|
- An issue is a formula of the row stating `output_type`: `"boolean"` stands while true; `"text"` stands while not empty,
|
|
224
226
|
its words the sentence the reader sees — use it when the sentence must say what or how much ("Short 4 of 10").
|
|
225
|
-
Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done.
|
|
227
|
+
Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done. A warning an
|
|
228
|
+
Act's `confirm` shows stands before the press: an issue that holds only at the stage the press lands on says nothing there.
|
|
226
229
|
- The list is priority: an issue blocking the next step leads, then the earlier in the list.
|
|
227
230
|
- `{ "rows": <link> }` on a parent rolls up every issue its child table declares, through a many-link paired to the
|
|
228
231
|
child's one-row link back. The platform keeps a count on the parent per child issue, `<link>_<issue>`, labelled
|
|
229
232
|
"<link label> · <issue label>"; never write it. The parent reads "2 rows left: Lines · Short".
|
|
230
|
-
- A formula reading `now()` or `isToday()` (
|
|
233
|
+
- A formula reading `now()` or `isToday()` (expiring within 30 days) is judged again nightly.
|
|
231
234
|
- An app's `Check` says what the issue does not: `on`, what it refuses in that app (`"update"`, `"all"`, or that
|
|
232
235
|
entity's Acts), and `resolve`, the Act that clears it; one stating neither is refused, and one without `on` names a
|
|
233
236
|
declared issue. A parent's Act is refused by a Check on the parent's count `on` that Act (never `"update"` or `"all"`: editing the rows clears it); the act then holds
|
|
234
237
|
the parent while it runs, so its own `workflow` cannot send mail, notify, run an agent or wait — start that work from a
|
|
235
238
|
workflow the act starts after.
|
|
236
|
-
-
|
|
237
|
-
is
|
|
239
|
+
- Read-only in this app is a Check refusing `"update"` (paid in full), in no `records.issues`; a lock on every door is
|
|
240
|
+
a row's `locked`, set by `update_records`: a locked row is corrected by a change stated with a reason (`request_change`) that a table manager approves, or the table's `locked_change: "tell"` writes at once.
|
|
238
241
|
- `get_table` reports each issue: rows holding it now, opened in the last 30 days, median days to clear.
|
|
239
242
|
|
|
240
243
|
An order whose lines can arrive short or unpriced, invoiced only when no line is short:
|
|
@@ -257,9 +260,9 @@ An order whose lines can arrive short or unpriced, invoiced only when no line is
|
|
|
257
260
|
## Look at it
|
|
258
261
|
|
|
259
262
|
After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` or its `record_id`
|
|
260
|
-
(with a `path` on that record: one Section is `/<record id>?section=<its title>`; `screen` for a later screen of a long one), up to six `pages` in one call — at a desk's width and a phone's, naming the columns a table left off at each width;
|
|
263
|
+
(with a `path` on that record: one Section is `/<record id>?section=<its title>`; `screen` for a later screen of a long one), up to six `pages` in one call, a page's `press` naming up to three controls pressed first (an act's form, a list's add form, a row's menu; the page drawn can write nothing) — at a desk's width and a phone's, naming the columns a table left off at each width, and under `Measured on this picture:` what a measurement of the shot found: the words a box cuts (px across, lines below), a page wider than its screen;
|
|
261
264
|
`-o <dir>` saves the shots from the CLI. `set_app` with `app_id`, an empty `body` and `dry_run` answers what a write of the
|
|
262
|
-
stored tree would be refused for now, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,
|
|
265
|
+
stored tree would be refused for now, and its notes, each under the heading of its kind: `Stated, and drawn differently:` (what the tree states that the app leaves out, moves, draws once or that changes nothing), `Suggestions:` (what the tree does not state) and `About this write:`. A note of the first two kinds is said by the write that earns it and counted on the next; `get_app` lists those that stand. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,
|
|
263
266
|
send the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
|
|
264
267
|
`period`, `icon`); tables and rows stay as they are.
|
|
265
268
|
|
|
@@ -267,13 +270,14 @@ send the tree saved before the change as `body` with `app_id`, nulling an App pr
|
|
|
267
270
|
|
|
268
271
|
Whether the build does the owner's work, answered by a call each, never from what you meant to write:
|
|
269
272
|
|
|
270
|
-
1. Each job
|
|
273
|
+
1. Each job done most often, and each their kind of business cannot run without: from the screen it starts on, which press does it? Find each on a `screenshot_app` shot, as a member who does it where access differs (`as_member`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`).
|
|
271
274
|
2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).
|
|
272
|
-
3. Is each kind of row in its treatment (`design/treatments`)?
|
|
275
|
+
3. Is each kind of row in its treatment (`design/treatments`)?
|
|
273
276
|
4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?
|
|
274
277
|
5. Is anything cramped at desk or phone width?
|
|
275
|
-
6. Is every paper and every exporting List's workbook made, those this kind of business sends unasked too, with no blank? Press each paper Act and read
|
|
278
|
+
6. Is every paper and every exporting List's workbook made, those this kind of business sends unasked too, with no blank? Press each paper Act and read its file; prove a List's `export: true` with `run_app_query` and `export`.
|
|
276
279
|
7. Can each row be recorded with what the person has now, its gap an issue, while only the step that needs the fact refuses? Is each thing that must never happen in this business (a step taken before its approval, stock below zero, a double booking) refused on every write? Prove each with a write sent `dry_run: true` that is refused (`workflows/table-checks`).
|
|
280
|
+
8. Does each daily job survive its exceptions (a step back, a locked record corrected, work in parts, late data, a cancel, a close before its work is done)? Prove each write with a `dry_run`.
|
|
277
281
|
|
|
278
282
|
A failed answer is a change to the tree, or a gap named to the owner.
|
|
279
283
|
|
|
@@ -287,32 +291,34 @@ Each kind of row's view is chosen before its List is written:
|
|
|
287
291
|
|---|---|---|
|
|
288
292
|
| People or organisations | `records.party`, with a photo or logo as its `image` | |
|
|
289
293
|
| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |
|
|
290
|
-
| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
|
|
294
|
+
| Read by their day, one diary of everyone's bookings | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
|
|
291
295
|
| Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | |
|
|
292
|
-
|
|
|
296
|
+
| Each person or room booked by the hour, where who is free matters | List `layout: {"lanes": {"by": …}}` by that person or room, and the table's `no_overlap` — a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |
|
|
293
297
|
| A day's work given out to people or vehicles | List `layout: {"lanes": {"by": …}}` over rows holding a day and no hour | `reference/lanes` |
|
|
294
298
|
| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
|
|
295
|
-
| Opened to be worked on | the Record's Sections — each one area of the record's data, its lists and field groups inside it; a status's stage acts stand at the foot of the
|
|
299
|
+
| Opened to be worked on | the Record's Sections — each one area of the record's data, its lists and field groups inside it; a status's stage acts stand at the foot of the Section whose work they end; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind | |
|
|
296
300
|
| Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes, and every row's ⋯ offers Duplicate; a List with `same` where read-only | |
|
|
297
301
|
| A related row's value on the list (the newest contract's end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |
|
|
298
302
|
| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | |
|
|
299
303
|
| Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab's `where` reads only what was true at the period's end, never a status the row moves on from | |
|
|
300
304
|
| Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | |
|
|
301
|
-
|
|
|
302
|
-
|
|
|
305
|
+
| Jobs that run over several days, each with a start and an end date | List `layout: {"lanes": {"by": …}}` by who or what does them, or `layout: {"gantt": {"start": …}}` where the jobs follow each other | `reference/lanes`, `reference/gantt` |
|
|
306
|
+
| Kept at a place: pallets, stock on shelves or in bins, anything found by its location on a floor or a map | List `layout: {"plan": …}` draws the floor, flat or in 3D, each thing where it stands; the places are rows of their own stating `plan_place`, so the tables follow this choice | `reference/plan` |
|
|
303
307
|
| Checked item by item against a standard | a List with `checklist: {"photo": …, "clause": …, "failed": […], "passed": …}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names — a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard's items, each item is a line marked the same way and filled by the block's columns | |
|
|
304
308
|
| A place before and after the work | a List with `compare: {"before": …, "after": …}`: two files fields read side by side, or two value fields read as one struck-then-new column | |
|
|
305
309
|
| Spots on a drawing | `records.pin: {"on": …, "x": …, "y": …}` on the spots' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row's `records.image` | `reference/record-places-pins-and-cadence` |
|
|
306
310
|
| Photos that must be taken on site | a files field with `photo_places: true` keeps where the device stood for each photo shot through the camera; judge them in a text formula `distance({photos}, {site_lat}, {site_lon})` listed in `records.issues` | `reference/formula` |
|
|
307
311
|
| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |
|
|
308
|
-
| The rows a weekly pattern owes (a class's lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": …, "on": "<a multi-select of mon–sun>", "start": …, "end": …, "planned": …, "except": …}]` on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern's hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |
|
|
309
|
-
| Who did what on which day | List `layout: "roster"` with the List of
|
|
312
|
+
| The rows a weekly pattern owes (a class's lessons on Tue and Thu at 16:00), or work owed every so many days, months or years (a machine's service every 6 months, an insurance every year) | `records.cadence: [{"entity": …, "on": "<a multi-select of mon–sun>", "start": …, "end": …, "planned": …, "except": …}]`, or `{"entity": …, "every": {"months": 6}, "from": "<a date of the row>", "planned": …}`, on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern's hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |
|
|
313
|
+
| Who did what on which day: one row per person per day (a rota, attendance) | List `layout: "roster"` over the people, with the List of those rows inside | `reference/roster` |
|
|
314
|
+
| Hours per person per day (a timesheet), a daily count, a meter reading | a roster whose cells List states one `{ field, edit: true }` number: each day is a box the number is typed in, a row's total beside its name and a day's total in a foot | `reference/roster` |
|
|
315
|
+
| Values typed down a list (prices, counts) | a List's column `{ field, edit: true }`: each row's value is its own cell, saved as that one field when typed; a press on the row still opens it, and on a phone the line reads the value, edited on the record | `reference/edit-column` |
|
|
310
316
|
| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record's `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` — a link a member makes of the record, never a seat; the link's page names the record only where the Outside states its title's field | |
|
|
311
317
|
| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |
|
|
312
318
|
| A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |
|
|
313
319
|
| A figure a record works out from its own figures (a payslip's net, an invoice's total) | a `Statement`: its lines in the order the arithmetic runs | `reference/statement-node` |
|
|
314
320
|
| Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |
|
|
315
|
-
| Papers an agent reads, where
|
|
321
|
+
| Papers an agent reads, where it pays for its run | an Act's `intake` with `fills` | |
|
|
316
322
|
| Calls and visits | an Act's `record` | |
|
|
317
323
|
| Changes a workflow proposes that a person approves row by row — a price list applied, a statement matched to what is owed | an Act's `workflow` with `review`, its body returning a changeset in `data.review` | |
|
|
318
324
|
| Documents covering lines | a List with `under` | |
|
|
@@ -335,7 +341,7 @@ or several members, draws their faces as a stack that names them on hover. Worke
|
|
|
335
341
|
|
|
336
342
|
`records.image` names the files field that pictures a row — a product's photo, a damage photo, a
|
|
337
343
|
scan, a receipt. Every row of it then leads with its picture, or its paper's preview, wherever it is drawn —
|
|
338
|
-
a row
|
|
344
|
+
a row leads with its picture, and where no row in view holds one no row keeps a place for it — a record's own page keeps it, where a person adds the photo; a link to it previews the file. `image` may instead name a
|
|
339
345
|
one-row link to a table with a picture (an order line's `item`), or a lookup of one through a one-row link (a delivery's `customer`, through its order): the row leads with that row's picture, still titled by
|
|
340
346
|
its own words — or several in order (`["product", "bundle"]`, a line linking either), the first that holds a picture leading the row. Never a field an Act keeps the paper it makes in (`into`). List
|
|
341
347
|
`layout: "cards"` where the picture is how a row is found. The table's `records.image_shape` (`portrait`, `square`, `landscape`) states the shape the register's cards and tiles and such a List draw it at. A files field the record keeps as a folder of
|
|
@@ -347,12 +353,21 @@ Every row an app draws opens on its page, the one you state or the one a write s
|
|
|
347
353
|
|
|
348
354
|
### Rows in time
|
|
349
355
|
|
|
350
|
-
Rows that each stand on a day, or hold a run of days or hours, are read where they stand in time
|
|
351
|
-
as two date columns. A row holds a span when two dates a person states are ordered, the second after the first by a
|
|
356
|
+
Rows that each stand on a day, or hold a run of days or hours, are read where they stand in time. A row holds a span when two dates a person states are ordered, the second after the first by a
|
|
352
357
|
`min` or a table check, both required or the second the row's `due`; else it is an appointment when one required date
|
|
353
358
|
is stated that no Act stamps, that a new row does not start at `today` and that is not derived. A stamp is an event,
|
|
354
|
-
and a `due`
|
|
355
|
-
a time each
|
|
359
|
+
and a `due` a deadline, never the day a row is held on; an end that is a promise (a loan's return day) is a `due`, since only a stated deadline is marked late. A `no_overlap` by a person or a value alone keeps one row at
|
|
360
|
+
a time each, read by what they hold.
|
|
361
|
+
|
|
362
|
+
Where a resource has several units (40 scaffold boards), a booking states how many it takes
|
|
363
|
+
(`quantity`, a number of the row) and the item states how many there are (`limit`, `"item.stock"`, a number of the one
|
|
364
|
+
row the `by` link names): a booking that would take more than are free on any day is refused, saying how many are free.
|
|
365
|
+
What counts is the most held at one moment, so hires of 10 on days 1–2 and
|
|
366
|
+
10 on days 8–9 leave 20 boards free for a hire of 5 over days 1–10. A row with no quantity holds nothing, an item with no
|
|
367
|
+
stock bounds nothing, a stock that does not compute refuses the booking, and lowering the stock below what is held from
|
|
368
|
+
today on is refused. A booking holds the days it states while it stands at a state `while` names. Rows
|
|
369
|
+
compete by a field holding one value each; by a link, they draw as lanes `by` it, each head saying what is free. An end may be a formula of the row (an
|
|
370
|
+
appointment's start plus its length), never one that reads the clock.
|
|
356
371
|
|
|
357
372
|
#### Calendar
|
|
358
373
|
|
|
@@ -367,11 +382,11 @@ runs to. The bare word takes both from the rows' facts and is refused, naming `d
|
|
|
367
382
|
machine, a room), each drawn even when empty: every row a block from the first date on its line to the
|
|
368
383
|
second, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed
|
|
369
384
|
within each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A
|
|
370
|
-
`no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field
|
|
385
|
+
`no_overlap` `by` the same link refuses two rows on one resource at once, and where it states a `quantity` or a `limit` the lane's head says how much is free on the day in view ("3 of 6 free"), the count a booking is refused by, whatever the view filters hide. A lane per person: `by` a member field
|
|
371
386
|
and `of` a group of the workspace by its id, each member of it a lane, idle ones too. Worked: `examples/lanes`.
|
|
372
387
|
|
|
373
388
|
A day's work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards
|
|
374
|
-
in lanes, those no lane holds, or holding no day, first in a tray. Each lane's head reads its count, its loads and its
|
|
389
|
+
in lanes, those no lane holds, or holding no day, first in a tray; a link the table requires puts every row in a lane as it is made, so only rows with no day reach the tray. Each lane's head reads its count, its loads and its
|
|
375
390
|
row's status; a lane its link no longer admits (`options_where`) says so in its head and refuses a card. Where the app writes the link, cards ticked or
|
|
376
391
|
dragged go to a lane in one write, every row checked before any is written, and the List's first `sort`, ascending on a
|
|
377
392
|
number the app writes, is a card's place in its lane.
|
|
@@ -398,7 +413,7 @@ a multi-select whose options are aliased `mon` to `sun`, and its times two `form
|
|
|
398
413
|
as a week strip wherever a person writes it; a Section holding the cadence's fields draws them as one week pattern; the
|
|
399
414
|
row's line reads it as one fact ("Tue, Thu · 16:00–17:30"); a roster of the child reads each row's own days. An Act
|
|
400
415
|
`makes: "<child>"` lists the rows still owed under the row each is made for, a group's count and tick at its head, a
|
|
401
|
-
row that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.
|
|
416
|
+
row that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). Work owed every so many days, months or years (a service, a renewal) is a cadence `every` from the day it starts (`from`, a date of the row, never today): it counts from that day each time, so a late service never moves the next one, and the Act that makes rows lists what is owed in the next twelve weeks; a yearly one beyond them shows "next on" its date on the row's line. Where the schedule should count from the day the work was done instead, the Act that records it `set`s `from` to that day. A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.
|
|
402
417
|
|
|
403
418
|
#### Agenda
|
|
404
419
|
|
|
@@ -410,7 +425,7 @@ date of the record.
|
|
|
410
425
|
|
|
411
426
|
A child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer — the
|
|
412
427
|
calls, visits and notes about the record, each with who and when, and its files where the child's `image`
|
|
413
|
-
names them.
|
|
428
|
+
names them. A team's discussion on a record is a `Comments` node (`reference/comments-node`). Entries planned ahead are an agenda; the status's moves are its history. Worked:
|
|
414
429
|
`examples/party`.
|
|
415
430
|
|
|
416
431
|
### Moves and numbers
|
|
@@ -419,47 +434,49 @@ names them. An app's Record draws no comment thread: a team's discussion on a re
|
|
|
419
434
|
|
|
420
435
|
The rows of a root List that a status stages towards its `closed` options move by Acts: each moves one option on to the next (`when` the
|
|
421
436
|
status holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a
|
|
422
|
-
condition a person sets. A value decided as a row reaches an outcome — why it was lost, refused, voided — is that
|
|
423
|
-
Act's `asks`,
|
|
437
|
+
condition a person sets. A value decided as a row reaches an outcome — why it was lost, refused, voided — is by default that
|
|
438
|
+
Act's `asks`, since a field to remember is left empty. An Act reaching past the workspace — sending an invoice
|
|
424
439
|
to a service, a letter by mail — runs its `workflow`, and what the workflow keeps from the answer (an invoice's id,
|
|
425
440
|
its link) is named in the Act's `set`. Work sent back for changes moves back to the earlier
|
|
426
441
|
step; a hold is a yes/no field (and its reason) the step's Acts wait on in their `when`; work only some rows take is a
|
|
427
|
-
stage's `when` (below);
|
|
442
|
+
stage's `when` (below); work done in parts (two deliveries, part payments) is a child row each, the parent moving on when they add up. An Act also moves a row back (`when` the later
|
|
428
443
|
stage, `set` the earlier), and without one a row moved on by mistake stays until an admin edits the table. What a
|
|
429
444
|
`workflow` or a paper did stands, so a way back there is a correction of its own.
|
|
430
445
|
|
|
431
446
|
#### Buttons
|
|
432
447
|
|
|
433
|
-
People mostly work through agents, so an app draws no
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
from
|
|
448
|
+
People mostly work through agents, so an app draws few buttons. Where no Act of a record's page states `button: true` or `false`, the Act
|
|
449
|
+
you state that moves the row to the next stage of its status draws as the page's button (a move the platform drafted stays in the status's own control), a move that
|
|
450
|
+
closes the record only when stated and no stage of the work follows it (a cancel listed after it is none); every other Act waits in the header's ⋯. `button: true` on each step a person does at that screen (a count received, a signed
|
|
451
|
+
paper, an approval), `button: false` on one only agents run (an invoice made from delivered orders, a payment matched
|
|
452
|
+
from a statement): once an Act of the page states `true` or `false`, the page draws exactly what is stated. A page leads with the move to its next stage; where a step that moves no stage is due first (opening a register before closing it), state `button: "lead"` on it (the first, where two do); the move to the next stage stays beside it. A move into the last stage states the condition it is due on (`when` or a Check) where the work before it can be unfinished. A drawer draws its
|
|
453
|
+
steps whatever `button` says. Rows never draw a button: every row act waits in its ⋯, and where many rows are worked,
|
|
454
|
+
tick them and state an act `on: "rows"`.
|
|
438
455
|
|
|
439
456
|
#### Stages
|
|
440
457
|
|
|
441
|
-
Work
|
|
442
|
-
|
|
458
|
+
Work nobody approves needs no approval stage: the row saved is the fact (a goods receipt nobody approves moves stock as
|
|
459
|
+
it is saved); an approval and its owner enter where this trade has a decider, named in the handover.
|
|
443
460
|
Name each job's work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long
|
|
444
461
|
matter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in
|
|
445
|
-
`records.status.stages` — its `owner` (a member field, a link's member field, or `{ "group": <id> }`, a member group) and its target
|
|
462
|
+
`records.status.stages` — its `owner` (a member field, a link's member field, or `{ "group": <id> }`, a member group: one with no one in it stops the step, and the app says so) and its target
|
|
446
463
|
`within` days — and the server holds it: only the owner's Acts move the row on, and a row created at a stage past the first is a move into that stage from nothing, which the stage's owner, an unowned stage's writer or a workspace admin (loading history) may make, on every path a row is written by, and a level an amount skips stands
|
|
447
464
|
named with why. A move forward passes each owned stage between that binds the row, each its owner's. A stage's `when`
|
|
448
465
|
names the rows it binds, held as an Act's `when` holds them on the row's own fields (a total a rollup sums or a yes/no a formula yields among them), as the row stood before a write
|
|
449
466
|
and as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while
|
|
450
467
|
smaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.
|
|
451
468
|
A row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options
|
|
452
|
-
that leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A stage's owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a
|
|
469
|
+
that leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A table whose people should be told states `tells: true` on its `status` and names each deadline that tells in `records.tells`; absent, no one is told. Whoever a row waits on then has one card in their inbox per stage, counted ("3 orders wait on you: Packed") and mailed once when it opens; a row joins it on reaching the stage, on a change of owner to them or when its deadline is three days off or passed, and leaves it when it moves on. It counts only rows the member can open in the app; the member who made a change is counted without being told, and work already waiting is recorded without telling anyone. A stage states `"tells": false` to be left out. `records.tells` names by a date's alias who is told: `true` for whoever the row waits on at its stage (else the owner of its first stage), a member field, `link.field` or `{ "group": <id> }`; a row at a closed option or settled is never told. A stage's owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a
|
|
453
470
|
register; a register whose job is a strict order, a first-come queue, states `attention: false`.
|
|
454
471
|
|
|
455
|
-
A status
|
|
472
|
+
A status the work walks through in order states `Steps` on its page, bare where no stage has a form, and it draws as a line across the page, each step naming its owner: only the author knows whether its options are a journey. A state a row moves between (active, paused, ended) states none, and draws in the head alone, as a select where a person moves it by hand. Where each stage has its own form to fill or its own list, the Record states each as a Section inside `Steps`, and the path draws down the page, each step holding what its stage holds; an act that asks one value and an act that files a paper need none. A part that is the work at every open stage is no step and states no `at`; `when` shows a part only at some stages.
|
|
456
473
|
|
|
457
474
|
#### Stage dates and history
|
|
458
475
|
|
|
459
476
|
A step reads as done only where the row shows it was reached, by a stamped date or a history move: a finished row with neither ticks none of its earlier steps, so a path whose steps should read states `dates`. Who changed what and when is the platform's audit trail, never a table and never shown by an app. When a stage's moment matters
|
|
460
477
|
to the business — reported, filtered, printed — it is a date on the row that `records.status.dates` stamps as the row
|
|
461
478
|
enters the option, whoever writes: the one way a status is timed, and the moment a stage's `within` runs from (each stage, and
|
|
462
|
-
each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a
|
|
479
|
+
each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a bare `Steps` draws it as a line of steps: no date fields or formulas copy it); a move whose
|
|
463
480
|
day may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per
|
|
464
481
|
status move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves
|
|
465
482
|
per person, or time in a stage a row re-enters. An event with facts of its own — a reason, an amount, a signature — is
|
|
@@ -468,13 +485,13 @@ stage is signed once per person, read off who moved the row.
|
|
|
468
485
|
|
|
469
486
|
#### Readings
|
|
470
487
|
|
|
471
|
-
A List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job's headline number —
|
|
488
|
+
A List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. `over` a date makes a figure a tile of the List's own period: its number, its change from the period before and its history. Any other figure that counts rows (no `value`) is said on the list's summary line, where a press narrows the rows to it; one that adds up a number stands as a tile, or on that line where it stands alone. A list's Tabs are one chip in its controls. Lead with the job's headline number —
|
|
472
489
|
its exception as a formula's yes/no in a Reading's `where` (what is short), never a stage the
|
|
473
|
-
status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then
|
|
490
|
+
status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then usually the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows, titled by them ("Price (open)"). A figure reads under its field's `label` over every row it sums, whatever stage each stands at: "Sell total" holds over all of them, where "Billed" holds only over rows already billed. A register with no such figure and no single select to split by gets no default band.
|
|
474
491
|
A grid (`by` and `across`) reads on a Sheet. A Sheet — a View of Readings at the App's root, beside its Lists or alone —
|
|
475
492
|
answers one owner's question across jobs, each Reading windowed by the reader's period (the App's `period`), and a
|
|
476
493
|
List on it hands over the rows to act on. A figure stated per party (owed, overdue, short) opens on the rows that make it,
|
|
477
|
-
listed on that party's page and adding up to it. Many Readings stand on several Sheets, each a View the reader picks. A question one app's rows answer goes on a Sheet there; one spanning apps gets a small app of its own. A Record's Readings read its own child rows.
|
|
494
|
+
listed on that party's page and adding up to it. Many Readings stand on several Sheets, each a View the reader picks. A question one app's rows answer goes on a Sheet there; one spanning apps gets a small app of its own. A Record's Readings read its own child rows. Worked: `examples/approval`, `examples/dashboard`.
|
|
478
495
|
|
|
479
496
|
#### Funnel
|
|
480
497
|
|
|
@@ -498,7 +515,7 @@ an app (`app_architecture`).
|
|
|
498
515
|
|
|
499
516
|
#### Sections
|
|
500
517
|
|
|
501
|
-
A record is a head, its parts and at most one Side. Its parts stack, one scroll with each headed
|
|
518
|
+
A record is a head, its parts and at most one Side. Its parts stack, one scroll with each headed. A record a person comes to for several jobs can group its parts into Tabs (`{ "type": "Tab", "label", "children" }`), one per job, each named for what a person opens it for and holding that job's Sections, Lists and fields; one shows at a time. Once a record states a Tab, every part stands in one, and `Steps` and the Side beside them; what a person needs whichever tab is open belongs in the head's `facts`, the steps or the Side, which stay in view. State few Tabs, each a page worth opening: a part of a few fields or one short List stands in a neighbouring Tab under its own heading, and a short record needs none. A part is one area of the record's data a person comes to for its own job; its related lists and field groups sit inside it under their headings. A status's stages are not areas (Stages). State each
|
|
502
519
|
part whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it
|
|
503
520
|
unstated. A stage that holds nothing needs no Section: the path draws it by its name. What a person needs in view at every part (who it is for, how to reach
|
|
504
521
|
them) goes in a Side: it leaves the head and stays on the rows; what only a stage's Act writes (an invoice's number,
|
|
@@ -507,7 +524,7 @@ stands in the head or the Side, never a Section. `row` changes how the app's row
|
|
|
507
524
|
Sections draws once, in the first; a Check stated in a Section guards the whole record.
|
|
508
525
|
|
|
509
526
|
The Record's Sections, in the order the work reaches them: the fields people write, a Field per paper the record
|
|
510
|
-
keeps, a child List per child, the Acts at each one's foot. A register's `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record's, and a figure that is final only from a stage is a Field of that stage's Section,
|
|
527
|
+
keeps, a child List per child your tree draws, the Acts at each one's foot. A register's `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record's, and a figure that is final only from a stage is a Field of that stage's Section, since a column shows it empty or wrong at earlier stages. A register laid out in time (calendar, lanes, roster) opens the
|
|
511
528
|
default record: every field a person writes. Behaviour belongs in an Act.
|
|
512
529
|
|
|
513
530
|
A Section of more than about six fields reads as Fieldsets of related facts: a patient's record holds "Contact" and
|
|
@@ -519,7 +536,7 @@ short field, one leaves the half beside that field empty.
|
|
|
519
536
|
|
|
520
537
|
Rows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on
|
|
521
538
|
its Record, `layout: "timeline"` where they are a log, `layout: {"agenda": …}` where they are planned on a day and within it, or
|
|
522
|
-
`layout: {"gantt": …}` where they are bars on a schedule. Which children a record lists is the author's — one of them at least. A List
|
|
539
|
+
`layout: {"gantt": …}` where they are bars on a schedule. Which children a record lists is the author's — one of them at least; the platform lists under a record only a child your tree draws elsewhere (a List of it in another record, or a Record page of it; a child a root List is over is that List's), so a child no List or Record draws is never listed, saved, added to or deleted from through the app, and a table the app only links to is read as a face to pick a row by. A List
|
|
523
540
|
listing only some of them narrows by its `where`: a select (one leg's fees), or a yes/no — a formula's for what is
|
|
524
541
|
still owed — on a List that adds no rows. A child List stating no `create` asks the table's required fields, natural key and
|
|
525
542
|
title; where defaults fill them all, it adds none. Rows on
|
|
@@ -549,8 +566,8 @@ A paper the business is brought and reads is an Act's `intake`: the press takes
|
|
|
549
566
|
them, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what
|
|
550
567
|
they state into the record's fields — a single link as a row the agent finds among those the app reads — shown before it is saved. Stated with `on: "view"` at the register's title, the papers make a NEW record instead: `fills` names what it requires, `<link>.<field>` fills the row a required link names (found on its entity's `natural_key`, else added), and the register opens the record made. Worked: `examples/case`.
|
|
551
568
|
|
|
552
|
-
An agent Act — an `intake`, a `record`'s `fills` — spends a run on every press, so it is stated
|
|
553
|
-
|
|
569
|
+
An agent Act — an `intake`, a `record`'s `fills` — spends a run on every press, so it is stated where an agent doing
|
|
570
|
+
that job is asked for or plainly saves more than it costs, named in the handover; otherwise a paper brought is its `expect` line, and a person types what it states.
|
|
554
571
|
|
|
555
572
|
#### Under
|
|
556
573
|
|
|
@@ -564,5 +581,6 @@ already on file (a supplier bill) picks them with `pick` instead; choose one per
|
|
|
564
581
|
|
|
565
582
|
An Act's `record`: the press records a call, visit or meeting — audio, transcript, screen where captured — and
|
|
566
583
|
files it as a new row of the record's `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill
|
|
567
|
-
that row's fields from the transcript, where
|
|
584
|
+
that row's fields from the transcript, where it pays for its run. Worked: `examples/calls`.
|
|
568
585
|
|
|
586
|
+
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
# Document Templates
|
|
2
2
|
|
|
3
|
-
Turn workspace data into finished documents — invoices, contracts,
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
many times as you like, feeding it data from records, a workflow, or an agent run.
|
|
3
|
+
Turn workspace data into finished documents — invoices, contracts, letters, emails — by filling a template registered
|
|
4
|
+
once, with data from records, a workflow or an agent run. A paper the owner hands over as a Word or Excel file
|
|
5
|
+
becomes a template of that type; an `html` template is for a paper with no file of its own.
|
|
7
6
|
|
|
8
7
|
This is a **capability + usage** guide. A tool's exact input schema is in its own description.
|
|
9
8
|
|
|
@@ -67,10 +66,10 @@ this host, give the person the file and a `person` drop link.
|
|
|
67
66
|
|
|
68
67
|
### By type
|
|
69
68
|
|
|
70
|
-
- **`html`** — a full HTML document with inline CSS and `{{variable}}` placeholders,
|
|
71
|
-
|
|
69
|
+
- **`html`** — a full HTML document with inline CSS and `{{variable}}` placeholders, printed to PDF.
|
|
70
|
+
`variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:
|
|
72
71
|
A0–A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page's own CSS,
|
|
73
|
-
`@page { size: 50mm 30mm }`. A change may send `edits`, anchored replacements in the stored markup, in place
|
|
72
|
+
`@page { size: 50mm 30mm }`, and it prints to the sheet's edge unless it states `@page { margin: 15mm }`. A change may send `edits`, anchored replacements in the stored markup, in place
|
|
74
73
|
of the whole `template`; `template_file_id` names an uploaded text file holding the markup, in place of `template`.
|
|
75
74
|
- **`pdf-form`** — an existing PDF filled in place. `set_template` with the uploaded `template_file_id`
|
|
76
75
|
answers `page_count` and `pages` (each page's `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`
|
|
@@ -82,9 +81,9 @@ this host, give the person the file and a `person` drop link.
|
|
|
82
81
|
ASCII and switches to Arimo past it.
|
|
83
82
|
- **`excel`** — a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet
|
|
84
83
|
that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out
|
|
85
|
-
is refused. A macro workbook is kept without its macros
|
|
86
|
-
time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables
|
|
87
|
-
|
|
84
|
+
is refused. A macro workbook is kept without its macros. Markers are validated at create
|
|
85
|
+
time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`.
|
|
86
|
+
`set_template` with `dry_run: true` runs every check, storing nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass
|
|
88
87
|
raw numbers, ISO dates and booleans at generate time; the cell's number format shows them. A cell's format also decides
|
|
89
88
|
what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).
|
|
90
89
|
A date cell reads a day or a moment written with no zone (`2026-09-30T08:15`) as that clock, and a moment written with
|
|
@@ -150,12 +149,15 @@ A field named like a function is read as the field, and calling the function the
|
|
|
150
149
|
```
|
|
151
150
|
get_template {"template_id": "dtl_…"} # its declared variables
|
|
152
151
|
generate_document {"document_template_id": "dtl_…", "filename": "invoice-1042",
|
|
153
|
-
"data": {"
|
|
152
|
+
"data": {"client_name": "Acme", "total": 1042, "items": [...]}}
|
|
154
153
|
```
|
|
155
154
|
|
|
156
155
|
- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for
|
|
157
156
|
`table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a
|
|
158
157
|
member or a link as `query_records`' `display` words, a number and a date raw.
|
|
158
|
+
- A Word, Excel, html or email template may print `{{organization.name}}` and `{{workspace.name}}`: the platform fills them from the
|
|
159
|
+
template's own workspace, so `data` never carries them. A `data` key `organization` (or `workspace`) that states a
|
|
160
|
+
`name` prints that name instead.
|
|
159
161
|
- `generate_document` renders the template's own type and returns a generated file object; take
|
|
160
162
|
its `file_id` onward.
|
|
161
163
|
- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is
|