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

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-ui-slots",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.2",
   "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": "6d74b362ba047678919b27c22f84e698dea48741"
 }

package/src/ReventlessSlots.res

@@ -32,14 +32,159 @@ 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 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"

package/src/ReventlessSlots.res.mjs

@@ -1,9 +1,154 @@
 // 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();
+  }
+}
+
+let Format = {
+  money: money$1,
+  day: day
+};
+
+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";
 
@@ -58,6 +203,10 @@ let ViewSlot = {
 export {
   h,
   RowSlot,
+  Row,
+  Format,
+  titleOf,
+  ensureStyles,
   ViewSlot,
 }
 /* No side effect */

package/src/ReventlessSlots.resi

@@ -119,6 +119,97 @@ 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 local date. `""` when it does not parse. */
+  let day: 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. */