@lotics/cli 0.290.0 → 0.291.0

package/docs/data_model.md

@@ -129,8 +129,8 @@ What `create_table` (on the CLI or in chat) and `update_table` take in `add_fiel
 `select_record_link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`. `button` is retired: an
 existing button field keeps running, but none is created, converted to or edited.
 
-A URL, an email, markdown, a checkbox, a datetime, a currency or a percentage is a `format` on
-another type, never a `type`:
+A URL, an email, markdown, a checkbox, a datetime, money, a quantity or a percentage is a `format`
+or a `notation` on another type, never a `type`:
 
 | Wanted | Field |
 |---|---|
@@ -138,8 +138,9 @@ another type, never a `type`:
 | Email or phone | `{ type: "text" }` |
 | Markdown | `{ type: "text", format: "markdown" }` |
 | Checkbox | `{ type: "boolean" }` |
-| Money | `{ type: "number", format: "currency", currency: "USD" }` |
-| Percentage | `{ type: "number", format: "percentage" }` |
+| Money | `{ type: "number", notation: { style: "currency", currency: "USD" } }` |
+| Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |
+| Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |
 | Datetime | `{ type: "date", format: "datetime" }` |
 | Date range | `{ type: "date", format: "date_range" }` |
 
@@ -150,14 +151,18 @@ may itself hold an object (`formula`, `aggregate_option`, `filter`, `order_by`);
 inside it. Each type takes only its own:
 
 - **text** — `format?` (`"text"` | `"link"` | `"markdown"`), `unique?`, `default_value?` (a string).
-- **number** — `format?` (`"number"` | `"currency"` | `"percentage"`), `currency?` (an ISO 4217
-  code), `unit?`, `unit_field?`, `currency_field?`, `default_value?` (a number). On `update_fields`,
-  null clears `currency`, `unit`, `unit_field` or `currency_field`.
-  - `unit`, beside format `"number"`: a measured code — g, kg, t, l, m3, cbm, mm, cm, m, km, m2,
-    min, h, day — or a counted noun such as `kiện`. A change between two units of one dimension
-    converts every stored figure; any other change relabels.
-  - `unit_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row's unit: every option label is a unit as `unit` takes one. In place of `unit`; only beside format "number".
-  - `currency_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row's currency: every option label is an ISO 4217 code. In place of `currency`; only beside format "currency".
+- **number** — `notation?`, `default_value?` (a number). `notation` is how the figure reads, one
+  of three; on `update_fields` a stated one replaces the field's whole.
+  - `{ style: "decimal" }` — a plain number, as a field stating none reads.
+  - `{ style: "currency", currency: "VND" }` — money in an ISO 4217 code.
+  - `{ style: "unit", unit }` — a quantity: `"percent"` (10 reads "10%", never multiplied), a
+    measured code — g, kg, t, l, m3, cbm, mm, cm, m, km, m2, min, h, day — or a counted noun such
+    as `kiện`. A change between two units of one dimension converts every stored figure; any other
+    change relabels.
+  - A currency or unit read on each row is `{ per_row: "ĐVT" }` in its place: a single select on
+    the same row, or a lookup of one through a one-link, named by name or key, whose chosen option
+    is that row's currency or unit — every option label an ISO 4217 code, or a unit as `unit`
+    takes one.
 - **date** — `format?` (`"date"` | `"datetime"` | `"date_range"` | `"datetime_range"`), `timezone?`,
   `derive_from?`, `default_value?` (a date string). `derive_from: "created_at"` stamps the row's
   creation once, `"updated_at"` re-stamps on every update; the field is then read-only, takes no
@@ -186,7 +191,7 @@ not exist yet, and option keys (`opt_…`) in `update_fields`.
 Read-only in records. `formula` is one key holding an object; a rollup's and a lookup's properties
 are separate keys on the field — `rollup: {…}` and `lookup: {…}` are refused as unrecognized.
 
-formula: { expression, format?, currency?, unit?, unit_field?, currency_field? }
+formula: { expression, notation?, link? }
 
 - `{Field Name}` or `{fld_key}` names a field of the same table, stored as its key, so a rename never
   breaks the formula. A reference to no field, or a call to something that is no helper, is refused.
@@ -194,9 +199,10 @@ formula: { expression, format?, currency?, unit?, unit_field?, currency_field? }
   `includes({Tags}, "opt_…")` for a multi.
 - The operators, the helpers and how an empty cell reads are the `model` reference, section `formula` — a model
   names fields by alias where a table tool names them by name or key; the language is the same.
-- On `update_fields` a key left out keeps its stored value, and null clears `currency`, `unit`,
-  `unit_field` or `currency_field`. `get_table` marks a formula that is null when every field it
-  reads is empty.
+- `notation` is how a number result reads, as a number field's; `link: true` says the result is a
+  URL, drawn as a link that opens.
+- On `update_fields` a key left out keeps its stored value, and a stated `notation` replaces the
+  stored one whole. `get_table` marks a formula that is null when every field it reads is empty.
 
 rollup — `source_field_key`, `aggregate_option: { field_key?, operation }`, `filter?`
 
@@ -207,9 +213,10 @@ rollup — `source_field_key`, `aggregate_option: { field_key?, operation }`, `f
   `min`, `max`, `range`; date: `earliest`, `latest`, `date_range`.
 - The cell's type comes from the OPERATION: `earliest` and `latest` hold a date, every other
   operation a number (`date_range` counts days). A "most recent linked date" is `latest` — `min` and
-  `max` are numeric and refuse a date. A rollup takes no format, currency or unit of its own: `sum`
-  over money carries the aggregated field's currency, over a weight its unit.
-- Over a figure read in each row's own unit or currency (`unit_field` / `currency_field`), `sum`,
+  `max` are numeric and refuse a date. A rollup takes no notation of its own: `sum` over money
+  reads in the aggregated field's currency, over a weight in its unit, a count as a plain number
+  and a `percent_*` in the unit `percent`.
+- Over a figure read in each row's own unit or currency (a notation's `per_row`), `sum`,
   `avg`, `median`, `min`, `max` and `range` hold only where that select is a lookup, through the
   link paired with `source_field_key`, of a single select on this table — the total reads in this
   row's option of it. A lookup of such a field has no unit.
@@ -227,13 +234,14 @@ lookup — `source_field_key`, `lookup_field_key`, `order_by?`
 ### Examples
 
 ```
-{ name: "Giá bán", type: "number", format: "currency", currency: "VND" }
-{ name: "Trọng lượng", type: "number", unit: "kg" }
-{ name: "Số lượng", type: "number", unit_field: "ĐVT" }
+{ name: "Giá bán", type: "number", notation: { style: "currency", currency: "VND" } }
+{ name: "Trọng lượng", type: "number", notation: { style: "unit", unit: "kg" } }
+{ name: "Số lượng", type: "number", notation: { style: "unit", unit: { per_row: "ĐVT" } } }
+{ name: "Chiết khấu", type: "number", notation: { style: "unit", unit: "percent" } }
 { name: "Trạng thái", type: "select", options: [{ name: "Mới" }, { name: "Xong" }] }
 { name: "Mã đơn", type: "autonumber", template: "SR-{YEAR}-{N:4}" }
 { name: "Khách hàng", type: "select_record_link", table_id: "tbl_x", sync_both_ways: true }
-{ name: "Total", type: "formula", formula: { expression: "{Price} * {Qty}", format: "currency", currency: "VND" } }
+{ name: "Total", type: "formula", formula: { expression: "{Price} * {Qty}", notation: { style: "currency", currency: "VND" } } }
 { name: "SL đã giao", type: "rollup", source_field_key: "Giao hàng", aggregate_option: { operation: "sum", field_key: "Số lượng" } }
 { name: "Customer Name", type: "lookup", source_field_key: "Customer", lookup_field_key: "Name" }
 { name: "Latest note", type: "lookup", source_field_key: "Calls", lookup_field_key: "Note", order_by: { field_key: "At", direction: "desc" } }

package/docs/examples.md

@@ -35,7 +35,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "booked_on", "type": "date"},
         {"alias": "parts_ready_on", "type": "date"},
         {"alias": "arrived_on", "type": "date"},
-        {"alias": "hours", "type": "number", "format": "number", "unit": "h"},
+        {"alias": "hours", "type": "number", "notation": {"style": "unit", "unit": "h"}},
         {"alias": "report", "type": "text", "format": "markdown"},
         {"alias": "completed_on", "type": "date"}
       ]
@@ -120,7 +120,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "booked_on", "type": "date"},
         {"alias": "parts_ready_on", "type": "date"},
         {"alias": "arrived_on", "type": "date"},
-        {"alias": "hours", "type": "number", "format": "number", "unit": "h"},
+        {"alias": "hours", "type": "number", "notation": {"style": "unit", "unit": "h"}},
         {"alias": "completed_on", "type": "date"}
       ]
     },
@@ -379,7 +379,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         },
         {"alias": "on_hand", "type": "number"},
         {"alias": "minimum", "type": "number"},
-        {"alias": "price", "type": "number", "format": "currency", "currency": "USD"},
+        {"alias": "price", "type": "number", "notation": {"style": "currency", "currency": "USD"}},
         {"alias": "supplier_page", "type": "text", "format": "link"},
         {"alias": "last_counted", "type": "date"},
         {"alias": "counted_by", "type": "select_member"},
@@ -394,7 +394,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "quantity", "type": "number"},
         {"alias": "shipped", "type": "number"},
         {"alias": "picked", "type": "number"},
-        {"alias": "unit_price", "type": "number", "format": "currency", "currency": "USD"},
+        {"alias": "unit_price", "type": "number", "notation": {"style": "currency", "currency": "USD"}},
         {"alias": "amount", "type": "formula"},
         {"alias": "category", "type": "lookup"}
       ]
@@ -493,7 +493,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "phone", "type": "text"},
         {"alias": "website", "type": "text", "format": "link"},
         {"alias": "account_manager", "type": "select_member"},
-        {"alias": "credit_limit", "type": "number", "format": "currency", "currency": "USD"},
+        {"alias": "credit_limit", "type": "number", "notation": {"style": "currency", "currency": "USD"}},
         {"alias": "outstanding", "type": "rollup"},
         {"alias": "over_limit", "type": "formula"},
         {
@@ -746,7 +746,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "sale", "type": "select_member"},
         {"alias": "xu_ly", "type": "select_member"},
         {"alias": "can_bo_sung", "type": "boolean"},
-        {"alias": "phi_dich_vu", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "phi_dich_vu", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {
           "alias": "loai_can",
           "type": "select",
@@ -758,7 +758,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           ]
         },
         {"alias": "can_boc", "type": "text"},
-        {"alias": "hoa_hong_sale", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "hoa_hong_sale", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {"alias": "ngay_thu_phi", "type": "date"},
         {"alias": "ngay_nhan_giay_to", "type": "date"},
         {"alias": "ngay_lap_ho_so", "type": "date"},
@@ -812,7 +812,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         },
         {"alias": "ngay_sinh", "type": "date"},
         {"alias": "cccd", "type": "text"},
-        {"alias": "thu_nhap", "type": "number", "format": "currency", "currency": "VND"}
+        {"alias": "thu_nhap", "type": "number", "notation": {"style": "currency", "currency": "VND"}}
       ]
     },
     {
@@ -828,7 +828,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           ]
         },
         {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},
-        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {
           "alias": "hinh_thuc",
           "type": "select",
@@ -1471,7 +1471,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           "target_entity": "nha_cung_cap",
           "cardinality": "one"
         },
-        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {"alias": "han_thanh_toan", "type": "date"},
         {
           "alias": "trang_thai",
@@ -1520,6 +1520,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
       "register": {
         "columns": ["nguoi_de_nghi"],
         "filters": ["nguoi_de_nghi", "du_an"],
+        "group": "du_an",
         "create": ["noi_dung", "loai", "du_an", "nha_cung_cap", "so_tien", "han_thanh_toan", "nguoi_de_nghi"],
         "readings": [
           {
@@ -1595,7 +1596,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           "type": "select",
           "options": [{"alias": "thu", "color": "green"}, {"alias": "chi", "color": "rose"}]
         },
-        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {"alias": "bien_dong", "type": "formula"},
         {
           "alias": "doi_tuong",

package/docs/filters.md

@@ -49,8 +49,9 @@ pass the whole list in one condition rather than splitting it across calls.
 | `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to` | a number |
 | `is_empty`, `is_not_empty` | none |
 
-A number whose field states `unit_field` or `currency_field` is read in each row's own unit or
-currency, so a comparison on it states `unit_option`: the option of that select its value is in.
+A number whose `notation` reads its unit or currency on each row (`{ "per_row": <select> }`) is
+read in each row's own, so a comparison on it states `unit_option`: the option of that select its
+value is in.
 Rows holding another option are out; measured units of one dimension convert.
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.290.0",
+  "version": "0.291.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {