@reventlessdev/reventless-spec 3.0.0-alpha.127 → 3.0.0-alpha.128

package/src/semantic/MemberRef.res

@@ -0,0 +1,119 @@
+/**
+A reference to a member of a collection the row already holds.
+
+The distinction this type exists to make is **input versus selection**. A field
+typed {!UploadableImage} says "give me a new file", and a UI reading it binds an
+upload endpoint. A field that must name a picture the row *already has* — remove
+this one, make that one primary, caption the third — says something else
+entirely, and before this type there was no way to say it: every such field was
+typed as the uploadable it selected among, so every one of them offered an
+uploader. On a remove command that is not merely odd, it is the opposite of what
+the command does.
+
+## What it declares, and what it does not
+
+It declares where the candidates are: a field of the row, by name. It declares
+no store — nothing is provisioned, no upload endpoint is bound — for the same
+reason {!ImageRef} declares none, and with the same consequence: a consumer
+asking `StorageRef.getFieldStore` gets `None`.
+
+The *semantic* is content-agnostic: one id serves images and documents, and what
+a member is comes from `~content`. That argument is optional and, where a caller
+gives it, redundant with the collection's own element type — deliberately, and
+for the reason {!UploadableImage} exists at all rather than a storage ref beside
+a content annotation. A consumer rendering one cell holds that field's schema and
+nothing else; it cannot reach a sibling's element type, so a declaration that
+made it look would be a declaration it could not read. Omit it and such a
+consumer falls back to its own rules, which is the right answer for a member type
+this vocabulary has no word for.
+
+## Why not `Reference.to_`
+
+A reference resolves its candidates by querying the target view's table. These
+candidates are on the row already in hand, so there is no query: same shape of
+answer, different resolution path, and pointing a query at it would scan a table
+to re-read a value the caller is holding. `Reference.toWithoutDcbTag` is the
+precedent that a payload can be reused without dragging DCB tagging along; this
+is the converse — a payload that resolves locally.
+
+## Where it goes
+
+**On a command field**, and there it means *pick one of these*:
+
+```rescript
+@schema type command =
+  | RemoveProductImage({
+      productId: @s.matches(DcbTag.string) string,
+      productImage: @s.matches(Reventless.MemberRef.of_(~view="Products", ~field="productImages")) string,
+    })
+```
+
+`~view` names the collection's view. Omit it on a declaration made *on* that
+view's own state, where the answer is "this record" — the wrapper walk below
+supports that position, and `getFieldTarget` reads it. Nothing in the framework
+declares one there today: a view that carried a scalar *and* the set it was
+drawn from needed a marker saying the two were one thing, and a view whose
+primary is simply the first member has no second field to reconcile.
+*/
+
+/** Transparent `string`, as every ref-shaped semantic here is: the marker
+    refines an existing field rather than replacing it, so nothing stored
+    changes when a field adopts it. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+/** Which collection a field names a member of. */
+type target = Semantic.memberTarget
+
+/**
+The sury schema for a field that selects a member of `field`.
+
+`~view` names the collection's view; omit it on a declaration made *on* that
+view's own state, where the answer is "this record". `~plugin` qualifies a view
+another plugin owns. `~content` names what the members are — pass
+`Semantic.Id.imageRef` for a set of pictures — so a reader holding this field
+alone still knows what it is drawing.
+
+No grammar is checked. The value is whatever the collection's own element type
+admits — a storage ref today, and checking the ref grammar a second time here
+would put {!StorageRef}'s rules in a second place to drift from. What makes a
+selection valid is that the row holds it, and only the decider knows that.
+*/
+let of_ = (
+  ~plugin: option<string>=?,
+  ~view: option<string>=?,
+  ~content: option<string>=?,
+  ~field: string,
+): S.t<t> =>
+  S.string->Semantic.mark(
+    ~id=Semantic.Id.memberRef,
+    ~payload=MemberOf({view, field, plugin, content}),
+  )
+
+/** The collection a schema names, if it carries the marker. */
+let getTarget = (schema: S.t<'a>): option<target> =>
+  switch Semantic.get(schema) {
+  | Some({payload: MemberOf(target)}) => Some(target)
+  | _ => None
+  }
+
+/**
+The collection a *field* names, looking through the wrappers around its value.
+
+The distinction `Reference.getFieldTarget` draws applies here for the same
+reason: `of_` returns an element schema, so on an `array<string>` of selections
+the marker sits on the string inside the array and the field's own schema
+carries nothing. Only the optional wrapper and the array element are followed —
+a marker on a nested record's field belongs to that field.
+*/
+let rec getFieldTarget = (schema: S.t<unknown>): option<target> =>
+  switch getTarget(schema) {
+  | Some(_) as found => found
+  | None =>
+    switch schema->Semantic.unwrapOptional->Option.getOr(schema) {
+    | Array({additionalItems: Schema(item)}) => getFieldTarget(item)
+    | _ => None
+    }
+  }

package/src/semantic/MemberRef.res.mjs

@@ -0,0 +1,57 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function of_(plugin, view, content, field) {
+  return Semantic$Reventless.mark(Sury.string, Semantic$Reventless.Id.memberRef, {
+    TAG: "MemberOf",
+    _0: {
+      view: view,
+      field: field,
+      plugin: plugin,
+      content: content
+    }
+  });
+}
+
+function getTarget(schema) {
+  let match = Semantic$Reventless.get(schema);
+  if (match === undefined) {
+    return;
+  }
+  let target = match.payload;
+  if (typeof target !== "object" || target.TAG !== "MemberOf") {
+    return;
+  } else {
+    return target._0;
+  }
+}
+
+function getFieldTarget(_schema) {
+  while (true) {
+    let schema = _schema;
+    let found = getTarget(schema);
+    if (found !== undefined) {
+      return found;
+    }
+    let match = Stdlib_Option.getOr(Semantic$Reventless.unwrapOptional(schema), schema);
+    if (match.type !== "array") {
+      return;
+    }
+    let item = match.additionalItems;
+    if (item === "strip" || item === "strict") {
+      return;
+    }
+    _schema = item;
+    continue;
+  };
+}
+
+export {
+  of_,
+  getTarget,
+  getFieldTarget,
+}
+/* sury Not a pure module */

package/src/semantic/Offload.res.mjs

@@ -110,7 +110,7 @@ function getStore(schema) {
     return;
   }
   let target = match.payload;
-  if (typeof target !== "object" || target.TAG === "ReferenceTo" || match.id !== Semantic$Reventless.Id.offload) {
+  if (typeof target !== "object" || target.TAG !== "StoredIn" || match.id !== Semantic$Reventless.Id.offload) {
     return;
   } else {
     return target._0;
@@ -123,7 +123,7 @@ function getThreshold(schema) {
     return;
   }
   let match$1 = match.payload;
-  if (typeof match$1 !== "object" || match$1.TAG === "ReferenceTo" || match.id !== Semantic$Reventless.Id.offload) {
+  if (typeof match$1 !== "object" || match$1.TAG !== "StoredIn" || match.id !== Semantic$Reventless.Id.offload) {
     return;
   } else {
     return match$1._0.threshold;

package/src/semantic/Percent.res

@@ -1,24 +1,9 @@
 /**
-Marks a `float` field as a percentage, expressed **0–100**.
+Marks a `float` field as a percentage, expressed **0–100**, not 0–1.
 
-## Why 0–100 and not 0–1
-
-Both conventions are defensible in the abstract, so the tie is broken by the
-consumer that already exists: the dashboard gauges a field with this semantic
-against fixed bounds of 0 and 100, and formats `42.0` as `"42%"`. Under a 0–1
-convention every value would render as a rounding error near zero — a gauge
-pinned at empty and a label reading `"0.42%"`.
-
-That failure is quiet, and it is quiet in the worst way: the numbers are
-*present* and *wrong*, and the layer at fault is not the one showing the symptom.
-Agreeing with the renderer costs nothing; disagreeing costs an afternoon.
-
-A fraction is still perfectly good arithmetic — it just multiplies by 100 before
-it becomes this type.
-
-## The grammar
-
-A finite number in `[0, 100]`. Fractions are allowed: `99.95` is a percentage.
+The scale is what every consumer gauges and formats against, so a fraction
+multiplies by 100 before it becomes this type. A finite number in `[0, 100]`;
+fractions are allowed — `99.95` is a percentage.
 
 @example
 ```rescript
@@ -30,7 +15,7 @@ A finite number in `[0, 100]`. Fractions are allowed: `99.95` is a percentage.
 */
 
 /** The percentage's representation. Transparent `float`: the marker refines an
-    existing numeric field rather than replacing it, so nothing stored changes. */
+    existing numeric field, so nothing stored changes. */
 type t = float
 
 external unsafe: float => t = "%identity"
@@ -51,3 +36,7 @@ let fromFloat = (raw: float): result<t, string> =>
 
 /** The sury schema for a percentage field. Use with `@s.matches(Reventless.Percent.schema)`. */
 let schema: S.t<t> = S.float->Semantic.refined(~id=Semantic.Id.percent, ~check=fromFloat)
+
+/** The percentage as text — `"42%"`, `"99.95%"`. Locale-independent, the way
+    `Money.format` is. */
+let format = (p: t): string => Float.toString(p) ++ "%"

package/src/semantic/Percent.res.mjs

@@ -26,8 +26,13 @@ function fromFloat(raw) {
 
 let schema = Semantic$Reventless.refined(Sury.float, Semantic$Reventless.Id.percent, fromFloat);
 
+function format(p) {
+  return p.toString() + "%";
+}
+
 export {
   fromFloat,
   schema,
+  format,
 }
 /* schema Not a pure module */

package/src/semantic/Semantic.res

@@ -18,11 +18,39 @@ type referenceTarget = {entity: string, plugin: option<string>}
     when it defers to the platform default. */
 type storeTarget = {plugin: option<string>, store: string, threshold: option<int>}
 
+/**
+Which collection a value names a member of.
+
+`field` is the collection's field name on the row — the only thing a consumer
+needs, because the candidates are already loaded. `view` names the view that
+collection belongs to and is absent where the answer is "the row this field is
+on", which is every declaration made on a view's own state. `plugin` is absent
+for the declaring plugin's own view, as everywhere else here.
+
+Unlike `referenceTarget` this is deliberately not resolvable by query: the
+members are on the row, so a consumer that went looking for a table has
+misread it.
+
+`content` names what a member *is* — an `imageRef`/`fileRef` id — and is the one
+part of this that is not about the collection. It rides here for the reason
+`uploadableImage` exists at all rather than `storageRef` beside a content
+annotation: the collection's own element type already says it, but a consumer
+holding one field's schema cannot reach a sibling's, and one that renders a cell
+holds exactly that. Absent leaves the reader to its own rules, which is what a
+host attaching something the vocabulary has no word for should get. */
+type memberTarget = {
+  view: option<string>,
+  field: string,
+  plugin: option<string>,
+  content: option<string>,
+}
+
 /** Per-semantic detail, for the semantics that carry any. */
 type payload =
   | Plain
   | ReferenceTo(referenceTarget)
   | StoredIn(storeTarget)
+  | MemberOf(memberTarget)
 
 /** A field's semantic: the vocabulary id, plus its detail. */
 type t = {id: string, payload: payload}
@@ -45,6 +73,16 @@ module Id = {
   let imageRef = "imageRef"
   let fileRef = "fileRef"
 
+  // An image and the text that goes with it, in one value. Declares its store
+  // the way `uploadableImage` does, on the record rather than on the reference
+  // inside it, so a field reader finds it through an array wrapper.
+  let captionedImage = "captionedImage"
+
+  // A selection rather than an input: the value names a member of a collection
+  // the row already holds. Declares no store, so nothing is provisioned and no
+  // upload endpoint is bound — the distinction `uploadableImage` could not make.
+  let memberRef = "memberRef"
+
   // Branded scalars: a refinement, so adopting one changes nothing stored.
   let email = "email"
   let phone = "phone"
@@ -116,6 +154,31 @@ let unwrapOptional = (schema: S.t<unknown>): option<S.t<unknown>> =>
   | _ => None
   }
 
+/**
+One arm of a command or event union, found by its tag.
+
+A union with exactly one constructor is emitted as a bare object carrying the
+TAG rather than a one-element `AnyOf`, so both shapes are matched.
+*/
+let unionVariant = (schema: S.t<unknown>, ~variant: string): option<S.t<unknown>> => {
+  let isVariant = (properties: dict<S.t<unknown>>) =>
+    switch properties->Dict.get("TAG") {
+    | Some(String({const: ?Some(name)})) => name == variant
+    | _ => false
+    }
+  switch schema {
+  | AnyOf({anyOf}) =>
+    anyOf->Array.find(arm =>
+      switch arm {
+      | Object({properties}) => isVariant(properties)
+      | _ => false
+      }
+    )
+  | Object({properties}) => isVariant(properties) ? Some(schema) : None
+  | _ => None
+  }
+}
+
 /**
 The semantic a field's schema carries, if any.
 

package/src/semantic/Semantic.res.mjs

@@ -13,6 +13,8 @@ let Id = {
   uploadableFile: "uploadableFile",
   imageRef: "imageRef",
   fileRef: "fileRef",
+  captionedImage: "captionedImage",
+  memberRef: "memberRef",
   email: "email",
   phone: "phone",
   url: "url",
@@ -67,6 +69,42 @@ function unwrapOptional(schema) {
   }
 }
 
+function unionVariant(schema, variant) {
+  let isVariant = properties => {
+    let match = properties["TAG"];
+    if (match === undefined) {
+      return false;
+    }
+    if (match.type !== "string") {
+      return false;
+    }
+    let name = match.const;
+    if (name !== undefined) {
+      return name === variant;
+    } else {
+      return false;
+    }
+  };
+  switch (schema.type) {
+    case "object" :
+      if (isVariant(schema.properties)) {
+        return schema;
+      } else {
+        return;
+      }
+    case "anyOf" :
+      return schema.anyOf.find(arm => {
+        if (arm.type === "object") {
+          return isVariant(arm.properties);
+        } else {
+          return false;
+        }
+      });
+    default:
+      return;
+  }
+}
+
 function getFrom(schema) {
   let found = Sury.$Metadata_get(schema, semanticId);
   if (found !== undefined) {
@@ -94,6 +132,7 @@ export {
   refined,
   showString,
   unwrapOptional,
+  unionVariant,
   getFrom,
   get,
   has,

package/src/semantic/StorageRef.res.mjs

@@ -70,7 +70,7 @@ function getStore(schema) {
     return;
   }
   let target = match.payload;
-  if (typeof target !== "object" || target.TAG === "ReferenceTo") {
+  if (typeof target !== "object" || target.TAG !== "StoredIn") {
     return;
   } else {
     return target._0;