@reventlessdev/reventless-ui-slots 3.0.0-alpha.1 → 3.0.0-alpha.3

package/README.md

@@ -93,6 +93,28 @@ let register = (arg: ReventlessSlots.registerArg) => {
 }
 ```
 
+### Helpers
+
+The ReScript surface carries a few things every slot module otherwise rewrites,
+and rewrites subtly wrong:
+
+| | |
+|---|---|
+| `Row.string` / `text` / `float` / `bool` / `array` | read a field out of the row's JSON. `text` treats `""` as absent, which is what a view writes for "not yet" |
+| `Row.money` + `Format.money` | `amount` is **minor units** at a scale the currency decides — 1000 is €10.00 but ¥1000 and 1.000 TND. `Format.money` asks `Intl` for the scale instead of assuming a hundred |
+| `Row.firstAttachment` | the `altText` and `caption` of a captioned set's first member. Text only: members hold storage **refs**, not URLs, and only `payload.image` is rebased for the deployment's origins |
+| `titleOf` | what the mode would have titled the row, falling back to its `name` |
+| `ensureStyles(~id, css)` | put a stylesheet in the page once. The shell re-imports a module on hot reload, so an unguarded injection appends the same rules on every save |
+
+They are ReScript-only, and deliberately: a ReScript module is bundled anyway, so
+importing a helper costs it nothing, while a JavaScript one is served as written
+and anything imported from this package would take away the no-bundler property
+that is that path's whole point. `index.js` stays one identity function.
+
+Call `ensureStyles` from inside `register`, not at module scope, so importing the
+module has no side effect — which is also what keeps it loadable by a test on
+Node, where there is no document.
+
 ### Why `h` rather than JSX
 
 Because React is the one thing a slot module must **not** bring its own copy of.
@@ -123,6 +145,11 @@ the question.
 | `tracker.summary` | row | the line beside one row's name; its summary fields |
 | `detail.media` | row | the media column of a `detailLayout: "media"` page; the record's picture |
 | `detail.aside` | row | above the field set on a `detailLayout: "media"` page; nothing by default |
+| `list.selection` | view | the bar over a list whose rows the caller can pick out: what is picked, a way to empty it, and the one command that takes the lot |
+
+`list.selection` is the one id that is not `<mode>.<region>`: it belongs to the
+list itself rather than to a mode, which is what lets a picking made in the table
+survive a switch to cards.
 
 An id nothing offers is reported to the console at boot — a renderer nothing will
 ever call is a mistake the running app would otherwise never mention.
@@ -134,7 +161,7 @@ ever call is a mistake the running app would otherwise never mention.
 { row, label?, image?, open?, actions? }
 
 // view slot
-{ rows, total?, selection?, run? }
+{ rows, total?, selection?, picked?, run? }
 ```
 
 `row` is the read model's own JSON. `image` is already resolved for this
@@ -142,10 +169,12 @@ deployment's asset origins. `actions` are already resolved against the
 deployment's declarations, the caller's permissions and the row's lifecycle
 state. `open` drills into the row.
 
-`selection` and `run` are declared and filled by nothing yet — cross-row
-selection is its own piece of work. They are in the contract from the start
-because discovering that a region needs a second arity after publishing would be
-a breaking change.
+`selection` is the picked row **ids**; `picked` is the rows behind them, each as
+the same row-slot payload above. Both, and not just the ids, because a list's
+window is replaced page by page: a row picked on page 1 is gone from `rows` by
+the time the caller is on page 3, and a bar whose job is to name what is in it
+cannot look one up. `run` takes the command's name and opens its form with the
+picked ids already in place.
 
 ## What a slot may not do
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-ui-slots",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.3",
   "description": "Types and one runtime helper for writing custom renderers into the regions of Reventless AutoUI's standard view modes.",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,7 +10,9 @@
     ".": {
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
-    }
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
   },
   "files": [
     "src/index.js",
@@ -52,5 +54,5 @@
     "react-dom": "^18.3.1",
     "rescript": "^12.3.0"
   },
-  "gitHead": "5877fd93c92d7f3d023e12a9f32e24832b639400"
+  "gitHead": "d2a7156f66c7f5f42837c6d5c13faf6d33a6df7e"
 }

package/src/ReventlessSlots.res

@@ -20,6 +20,7 @@ type viewPayload = {
   rows: array<JSON.t>,
   total?: int,
   selection?: array<string>,
+  picked?: array<rowPayload>,
   run?: string => unit,
 }
 
@@ -32,14 +33,172 @@ type slots = {
 
 type registerArg = {h: hyperscript, slots: slots}
 
-// `React.createElement(tag, props, ...children)` against the function the shell
-// passed in. Written as `%raw` because the callee is a value rather than a
-// module member, which `@variadic` cannot express.
-let h: (hyperscript, 'tag, 'props, array<React.element>) => React.element = %raw(`
-  function (h, tag, props, children) {
-    return h(tag, props, ...children)
+/* `React.createElement(tag, props, ...children)` against the function the shell
+   passed in.
+
+   `@variadic` cannot express this: it binds a module member, and the callee here
+   is a value that arrived as an argument. So the call goes through
+   `Function.prototype.apply`, which is exactly "call this value with these
+   arguments" and is the one thing in JavaScript that takes an argument list as
+   data.
+
+   `apply` rather than handing React the array as a single child, which would
+   also compile: React reads an array child as a keyed list and warns about
+   missing keys, where positional children carry no such expectation. The
+   distinction is invisible until a slot author's console fills up. */
+
+// One element of that argument list. Heterogeneous by nature — a tag, then
+// props, then elements — so the three are widened to a common type on the way
+// in. Nothing reads an `arg` back out; it exists only to be passed on.
+//
+// `args` widens the children array in one step rather than per element: mapping
+// `arg` over it would compile to an identity `.map`, allocating a second array
+// on every element built.
+type arg
+external arg: 'a => arg = "%identity"
+external args: array<React.element> => array<arg> = "%identity"
+
+@send
+external applyTo: (hyperscript, Nullable.t<unit>, array<arg>) => React.element = "apply"
+
+let h = (hyperscript: hyperscript, tag: 'tag, props: 'props, children: array<React.element>) =>
+  hyperscript->applyTo(Nullable.null, [arg(tag), arg(props)]->Array.concat(args(children)))
+
+// Reading the row's JSON. One right answer per field type, so it lives here
+// rather than being rewritten — subtly differently — per deployment.
+module Row = {
+  let field = (row: JSON.t, name: string): option<JSON.t> =>
+    switch row {
+    | Object(fields) => fields->Dict.get(name)
+    | _ => None
+    }
+
+  let string = (row: JSON.t, name: string): option<string> =>
+    switch field(row, name) {
+    | Some(String(value)) => Some(value)
+    | _ => None
+    }
+
+  let text = (row: JSON.t, name: string): option<string> =>
+    switch string(row, name) {
+    | Some("") | None => None
+    | Some(value) => Some(value)
+    }
+
+  let float = (row: JSON.t, name: string): option<float> =>
+    switch field(row, name) {
+    | Some(Number(value)) => Some(value)
+    | _ => None
+    }
+
+  let bool = (row: JSON.t, name: string): option<bool> =>
+    switch field(row, name) {
+    | Some(Boolean(value)) => Some(value)
+    | _ => None
+    }
+
+  let array = (row: JSON.t, name: string): option<array<JSON.t>> =>
+    switch field(row, name) {
+    | Some(Array(values)) => Some(values)
+    | _ => None
+    }
+
+  let money = (row: JSON.t, name: string): option<(float, string)> =>
+    switch field(row, name) {
+    | Some(Object(value)) =>
+      switch (value->Dict.get("amount"), value->Dict.get("currency")) {
+      | (Some(Number(amount)), Some(String(currency))) => Some((amount, currency))
+      | _ => None
+      }
+    | _ => None
+    }
+
+  let firstAttachment = (row: JSON.t, name: string): option<(option<string>, option<string>)> => {
+    let nonEmpty = (member: Dict.t<JSON.t>, key: string) =>
+      switch member->Dict.get(key) {
+      | Some(String("")) | None => None
+      | Some(String(value)) => Some(value)
+      | Some(_) => None
+      }
+    switch field(row, name) {
+    | Some(Array(members)) =>
+      switch members->Array.get(0) {
+      | Some(JSON.Object(first)) => Some((nonEmpty(first, "altText"), nonEmpty(first, "caption")))
+      | _ => None
+      }
+    | _ => None
+    }
+  }
+}
+
+module Format = {
+  let money = ((amount, currency): (float, string)): string => {
+    let format = Intl.NumberFormat.make(~options={style: #currency, currency})
+    let digits = switch Intl.NumberFormat.resolvedOptions(format).maximumFractionDigits {
+    | Some(digits) => (digits :> int)
+    | None => 2
+    }
+    Intl.NumberFormat.format(format, amount /. Math.pow(10.0, ~exp=Int.toFloat(digits)))
+  }
+
+  let day = (iso: string): string => {
+    let at = Date.fromString(iso)
+    Float.isNaN(Date.getTime(at)) ? "" : Date.toLocaleDateString(at)
+  }
+
+  let pad = (n: int): string => n < 10 ? "0" ++ Int.toString(n) : Int.toString(n)
+
+  let isoDay = (iso: string): string => {
+    let at = Date.fromString(iso)
+    Float.isNaN(Date.getTime(at))
+      ? ""
+      : Int.toString(Date.getFullYear(at)) ++
+        "-" ++
+        pad(Date.getMonth(at) + 1) ++
+        "-" ++
+        pad(Date.getDate(at))
+  }
+}
+
+let titleOf = (payload: rowPayload): string =>
+  switch payload.label {
+  | Some(label) => label
+  | None => Row.string(payload.row, "name")->Option.getOr("")
+  }
+
+// The DOM calls `ensureStyles` makes. Bound here rather than pulled from a DOM
+// binding package, so this package keeps its single dependency.
+//
+// `document` is reached through `globalThis` rather than as a bare global, and
+// that is the load-bearing detail: referencing an undeclared `document` throws a
+// ReferenceError on Node, while `globalThis.document` is simply `undefined`
+// there. It is what lets a slot module be imported and driven by a test.
+module Dom = {
+  type document
+  type element
+
+  @val @scope("globalThis") external document: Nullable.t<document> = "document"
+  @send external getElementById: (document, string) => Nullable.t<element> = "getElementById"
+  @send external createElement: (document, string) => element = "createElement"
+  @get external head: document => element = "head"
+  @set external setId: (element, string) => unit = "id"
+  @set external setTextContent: (element, string) => unit = "textContent"
+  @send external appendChild: (element, element) => unit = "appendChild"
+}
+
+let ensureStyles = (~id: string, css: string): unit =>
+  switch Nullable.toOption(Dom.document) {
+  | None => ()
+  | Some(doc) =>
+    switch Nullable.toOption(doc->Dom.getElementById(id)) {
+    | Some(_) => ()
+    | None =>
+      let style = doc->Dom.createElement("style")
+      style->Dom.setId(id)
+      style->Dom.setTextContent(css)
+      doc->Dom.head->Dom.appendChild(style)
+    }
   }
-`)
 
 module RowSlot = {
   let cardsFace = "cards.face"
@@ -63,5 +222,6 @@ module RowSlot = {
 module ViewSlot = {
   let cardsEmpty = "cards.empty"
   let galleryEmpty = "gallery.empty"
-  let all = [cardsEmpty, galleryEmpty]
+  let listSelection = "list.selection"
+  let all = [cardsEmpty, galleryEmpty, listSelection]
 }

package/src/ReventlessSlots.res.mjs

@@ -1,9 +1,166 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
-let h = (function (h, tag, props, children) {
-    return h(tag, props, ...children)
+function h(hyperscript, tag, props, children) {
+  return hyperscript.apply(null, [
+    tag,
+    props
+  ].concat(children));
+}
+
+function field(row, name) {
+  if (typeof row === "object" && row !== null && !Array.isArray(row)) {
+    return row[name];
+  }
+}
+
+function string(row, name) {
+  let match = field(row, name);
+  if (typeof match === "string") {
+    return match;
+  }
+}
+
+function text(row, name) {
+  let value = string(row, name);
+  if (value !== undefined && value !== "") {
+    return value;
+  }
+}
+
+function float(row, name) {
+  let match = field(row, name);
+  if (typeof match === "number") {
+    return match;
+  }
+}
+
+function bool(row, name) {
+  let match = field(row, name);
+  if (typeof match === "boolean") {
+    return match;
+  }
+}
+
+function array(row, name) {
+  let match = field(row, name);
+  if (Array.isArray(match)) {
+    return match;
+  }
+}
+
+function money(row, name) {
+  let match = field(row, name);
+  if (match === undefined) {
+    return;
+  }
+  if (typeof match !== "object" || match === null || Array.isArray(match)) {
+    return;
+  }
+  let match$1 = match["amount"];
+  let match$2 = match["currency"];
+  if (typeof match$1 === "number" && typeof match$2 === "string") {
+    return [
+      match$1,
+      match$2
+    ];
+  }
+}
+
+function firstAttachment(row, name) {
+  let nonEmpty = (member, key) => {
+    let match = member[key];
+    if (typeof match === "string" && match !== "") {
+      return match;
+    }
+  };
+  let match = field(row, name);
+  if (match === undefined) {
+    return;
+  }
+  if (!Array.isArray(match)) {
+    return;
+  }
+  let match$1 = match[0];
+  if (typeof match$1 === "object" && match$1 !== null && !Array.isArray(match$1)) {
+    return [
+      nonEmpty(match$1, "altText"),
+      nonEmpty(match$1, "caption")
+    ];
+  }
+}
+
+let Row = {
+  field: field,
+  string: string,
+  text: text,
+  float: float,
+  bool: bool,
+  array: array,
+  money: money,
+  firstAttachment: firstAttachment
+};
+
+function money$1(param) {
+  let format = new Intl.NumberFormat(undefined, {
+    currency: param[1],
+    style: "currency"
   });
+  let digits = format.resolvedOptions().maximumFractionDigits;
+  let digits$1 = digits !== undefined ? digits : 2;
+  return format.format(param[0] / Math.pow(10.0, digits$1));
+}
+
+function day(iso) {
+  let at = new Date(iso);
+  if (Number.isNaN(at.getTime())) {
+    return "";
+  } else {
+    return at.toLocaleDateString();
+  }
+}
+
+function pad(n) {
+  if (n < 10) {
+    return "0" + n.toString();
+  } else {
+    return n.toString();
+  }
+}
+
+function isoDay(iso) {
+  let at = new Date(iso);
+  if (Number.isNaN(at.getTime())) {
+    return "";
+  } else {
+    return at.getFullYear().toString() + "-" + pad(at.getMonth() + 1 | 0) + "-" + pad(at.getDate());
+  }
+}
+
+function titleOf(payload) {
+  let label = payload.label;
+  if (label !== undefined) {
+    return label;
+  } else {
+    return Stdlib_Option.getOr(string(payload.row, "name"), "");
+  }
+}
+
+function ensureStyles(id, css) {
+  let doc = globalThis.document;
+  if (doc == null) {
+    return;
+  }
+  let match = doc.getElementById(id);
+  if (!(match == null)) {
+    return;
+  }
+  let style = doc.createElement("style");
+  style.id = id;
+  style.textContent = css;
+  doc.head.appendChild(style);
+}
 
 let cardsFace = "cards.face";
 
@@ -44,20 +201,34 @@ let cardsEmpty = "cards.empty";
 
 let galleryEmpty = "gallery.empty";
 
+let listSelection = "list.selection";
+
 let all$1 = [
   cardsEmpty,
-  galleryEmpty
+  galleryEmpty,
+  listSelection
 ];
 
 let ViewSlot = {
   cardsEmpty: cardsEmpty,
   galleryEmpty: galleryEmpty,
+  listSelection: listSelection,
   all: all$1
 };
 
+let Format = {
+  money: money$1,
+  day: day,
+  isoDay: isoDay
+};
+
 export {
   h,
   RowSlot,
+  Row,
+  Format,
+  titleOf,
+  ensureStyles,
   ViewSlot,
 }
 /* No side effect */

package/src/ReventlessSlots.resi

@@ -42,17 +42,21 @@ type rowPayload = {
   actions?: array<action>,
 }
 
-/** What a per-view region is handed. `selection` and `run` are declared and
-    filled by nothing yet — cross-row selection is its own piece of work. They
-    are in the contract from the start because discovering that a region needs a
-    second arity after publishing would be a breaking change. */
+/** What a per-view region is handed. */
 type viewPayload = {
   /** The rows the mode is currently drawing — its page window, not the table. */
   rows: array<JSON.t>,
   /** How many rows that window holds. */
   total?: int,
-  /** Row ids the caller has picked out, where the mode offers picking. */
+  /** Row ids the caller has picked out, where the view offers picking. */
   selection?: array<string>,
+  /** The rows behind `selection`, as they were when picked.
+
+      A list's window is replaced page by page, so a row picked on page 1 is
+      gone from `rows` by the time the caller is on page 3 — and a bar whose job
+      is to name what is in it cannot look one up. So the rows travel, each as
+      the same `rowPayload` a per-row region is handed. */
+  picked?: array<rowPayload>,
   /** Start the region's one command, by name. */
   run?: string => unit,
 }
@@ -119,11 +123,123 @@ module RowSlot: {
   let all: array<string>
 }
 
+/* ── Helpers ────────────────────────────────────────────────────────────────
+
+   Everything below is runtime code, and it is ReScript-only on purpose rather
+   than by omission.
+
+   A ReScript slot module is bundled before it is served, so importing a helper
+   costs it nothing. A JavaScript one is served as written — no bundler, no
+   dependency, which is that path's whole point — and anything it imported from
+   this package would take that away. `index.js` therefore stays what it is: one
+   identity function for the type checker, and no runtime to depend on.
+
+   The JS contract is the same contract; it just reads its own fields. */
+
+/** Reading the row you were handed.
+
+    `row` is the read model's own JSON, so every renderer that shows a field has
+    to get it out of a `JSON.t` — and there is one right answer per field type,
+    which is why these are here rather than rewritten per deployment. None of
+    them reaches past the payload: they read what `rowPayload` already carries. */
+module Row: {
+  /** One field, whatever its type. */
+  let field: (JSON.t, string) => option<JSON.t>
+
+  /** A string field. `None` when absent or not a string. */
+  let string: (JSON.t, string) => option<string>
+
+  /** A string field that actually says something.
+
+      Distinct from `string` because a view writes `""` for "not yet" — an order
+      that has not shipped carries `shippedAt: ""` — and a blank is not a value
+      to render. Take this one wherever an empty string should read as absent. */
+  let text: (JSON.t, string) => option<string>
+
+  /** A number field. */
+  let float: (JSON.t, string) => option<float>
+
+  /** A boolean field. */
+  let bool: (JSON.t, string) => option<bool>
+
+  /** An array field, as raw elements. */
+  let array: (JSON.t, string) => option<array<JSON.t>>
+
+  /** A `Money` field: whole minor units and the currency they are in.
+
+      Reventless serialises money as `{amount, currency}` where `amount` is
+      **minor units** — 1000 is €10.00, ¥1000 or 1.000 TND depending on the
+      currency. Pair it with `Format.money`, which asks `Intl` for the scale
+      rather than assuming a hundred. */
+  let money: (JSON.t, string) => option<(float, string)>
+
+  /** The first member of a captioned attachment set, as `(altText, caption)`.
+
+      Reventless serialises these as `{ref, altText?, caption?}`, where `ref` is
+      a **storage ref, not a URL**: only `rowPayload.image` is rebased for this
+      deployment's asset origins. So this reads the *text* of a member, never its
+      picture — resolving one is the producer's job. */
+  let firstAttachment: (JSON.t, string) => option<(option<string>, option<string>)>
+}
+
+/** Turning values into the strings a region shows. */
+module Format: {
+  /** Money, at the scale its currency actually uses.
+
+      Takes what `Row.money` returns. The number of minor units per unit comes
+      from `Intl` rather than being assumed to be a hundred, which is right for
+      most currencies and quietly wrong for JPY and TND. */
+  let money: ((float, string)) => string
+
+  /** An ISO instant as a short date **in the viewer's own locale**.
+
+      Which format that is comes from the runtime, not from you or from the
+      deployment: the same order reads `9/4/2026` to one customer and `04/09/2026`
+      to another, and a screenshot never matches CI. That is right for a surface
+      whose readers are the public, and wrong wherever a date has to be
+      unambiguous or stable — take `isoDay` there. */
+  let day: string => string
+
+  /** An ISO instant as `YYYY-MM-DD`, the same everywhere.
+
+      Built from the **local** calendar parts rather than by slicing the string,
+      which would silently publish the UTC date and land a day out either side of
+      midnight for most of the world. */
+  let isoDay: string => string
+}
+
+/** What the mode would have titled this row, else the row's own `name`.
+
+    The precedence is the contract's, not the deployment's: `label` is what the
+    producer resolved, and a renderer that preferred the raw field would ignore
+    it. */
+let titleOf: rowPayload => string
+
+/** Put a stylesheet in the page, once, under an id of your choosing.
+
+    Slot modules ship their own CSS and there is nowhere else to put it. Doing it
+    by hand is easy to get subtly wrong: the shell re-imports a module on a hot
+    reload, so an unguarded injection appends the same rules again on every save.
+    This no-ops when the id is already present, and no-ops entirely outside a
+    browser so a module stays loadable by a test on Node.
+
+    Call it from `register` rather than at module scope, so importing the module
+    has no side effect. */
+let ensureStyles: (~id: string, string) => unit
+
 /** Per-view slots the shipped modes offer. */
 module ViewSlot: {
   /** The card grid when the view has no rows. */
   let cardsEmpty: string
   /** The tile grid when the view has no rows. */
   let galleryEmpty: string
+  /** The bar over a list whose rows the caller can pick out: what is picked, a
+      way to empty it, and the one command that takes the lot.
+
+      Offered by the list producer rather than by a view mode — the first id
+      that is not `<mode>.<region>`. The list renders the mode inside its own
+      chrome and the bar is that chrome, so a picking made in the table survives
+      a switch to cards and the bar has to outlive both. */
+  let listSelection: string
   let all: array<string>
 }

package/src/index.d.ts

@@ -48,19 +48,21 @@ export interface RowPayload<Row = Record<string, unknown>> {
   actions?: SlotAction[]
 }
 
-/** What a per-view region is handed.
- *
- *  `selection` and `run` are declared and filled by nothing yet: cross-row
- *  selection is its own piece of work. They are here from the start because
- *  discovering that a region needs a second arity after the contract is
- *  published would be a breaking change. */
+/** What a per-view region is handed. */
 export interface ViewPayload<Row = Record<string, unknown>> {
   /** The rows the mode is currently drawing — its page window, not the table. */
   rows: Row[]
   /** How many rows that window holds. */
   total?: number
-  /** Row ids the caller has picked out, where the mode offers picking. */
+  /** Row ids the caller has picked out, where the view offers picking. */
   selection?: string[]
+  /** The rows behind `selection`, as they were when picked.
+   *
+   *  A list's window is replaced page by page, so a row picked on page 1 is gone
+   *  from `rows` by the time the caller is on page 3 — and a bar whose job is to
+   *  name what is in it cannot look one up. So the rows travel, each as the same
+   *  `RowPayload` a per-row region is handed. */
+  picked?: RowPayload<Row>[]
   /** Start the region's one command, by name. */
   run?: (command: string) => void
 }
@@ -126,8 +128,14 @@ export type RowSlotId =
  * | --- | --- |
  * | `cards.empty` | the card grid when the view has no rows |
  * | `gallery.empty` | the tile grid when the view has no rows |
+ * | `list.selection` | the bar over a list whose rows the caller can pick out |
+ *
+ * `list.selection` is the one id that is not `<mode>.<region>`: it belongs to
+ * the list producer, not to a mode. The list renders the mode inside its own
+ * chrome and the bar is that chrome, so a picking made in the table survives a
+ * switch to cards and the bar has to outlive both.
  */
-export type ViewSlotId = 'cards.empty' | 'gallery.empty'
+export type ViewSlotId = 'cards.empty' | 'gallery.empty' | 'list.selection'
 
 /**
  * Identity helper: type-checks a `register` function without changing it.