@colisweb/rescript-toolkit 2.67.0 → 2.68.0

package/playground/custom.css

@@ -155,9 +155,12 @@
 }
 
 h2 {
-  @apply text-2xl font-display font-bold;
+  @apply text-3xl font-display font-bold;
 }
 h3 {
+  @apply text-2xl font-display font-bold;
+}
+h4 {
   @apply text-xl font-display font-bold;
 }
 

package/playground/design/Playground_DesignSystem.res

@@ -0,0 +1,12 @@
+module Fonts = {
+  @module("../../../../playground/design/DesignSystem_Fonts.mdx") @react.component
+  external make: unit => React.element = "default"
+}
+module Colors = {
+  @module("../../../../playground/design/DesignSystem_Colors.mdx") @react.component
+  external make: unit => React.element = "default"
+}
+module MediaQueries = {
+  @module("../../../../playground/design/DesignSystem_MediaQueries.mdx") @react.component
+  external make: unit => React.element = "default"
+}

package/playground/{stories/TailwindConfigBreakpoints.js → design/TailwindConfigBreakpoints.jsx}

@@ -1,4 +1,4 @@
-import tailwindConfig from "../src/tailwind/tailwind.config";
+import * as tailwindConfig from "../../src/tailwind/tailwind.config.js";
 
 const screens = tailwindConfig.theme.screens;
 

package/playground/{stories/TailwindConfigColorsPreview.js → design/TailwindConfigColorsPreview.jsx}

@@ -1,4 +1,4 @@
-import tailwindConfig from "../../src/tailwind/tailwind.config";
+import * as tailwindConfig from "../../src/tailwind/tailwind.config.js";
 
 const colors = tailwindConfig.theme.colors;
 

package/playground/{stories/TailwindConfigFontsPreview.js → design/TailwindConfigFontsPreview.jsx}

@@ -1,4 +1,4 @@
-import tailwindConfig from "../src/tailwind/tailwind.config";
+import * as tailwindConfig from "../../src/tailwind/tailwind.config.js";
 
 const fontFamily = tailwindConfig.theme.fontFamily;
 const fontSize = tailwindConfig.theme.fontSize;

package/playground/docs/ApiDecoding.mdx

@@ -0,0 +1,70 @@
+# Decode content from API result
+
+## API
+
+### Decode an enumeration
+
+```rescript
+module LiftEnum = {
+  @deriving(jsConverter)
+  type enum = [
+    | #withLift
+    | #withoutLift
+    | #unknown
+  ]
+}
+
+module Lift = Toolkit.Decoder.Enum(LiftEnum)
+
+@decco
+type response = {lift: Lift.t}
+```
+
+### Decode a date
+
+```rescript
+@decco
+type response = {
+  createdAt: Toolkit.Decoder.Date.t
+}
+```
+
+### Decode unit measure
+
+There are 2 options :
+
+- the field has the unit like : `19 mm`
+- the field has only the value
+
+#### Automatic unit handling
+
+```rescript
+[@decco]
+type response = {
+  length: Toolkit.Decoder.UnitMeasure.Dimension.WithUnit.t
+}
+```
+
+#### Known unit
+
+```rescript
+[@decco]
+type response = {
+  weight: Toolkit.Decoder.UnitMeasure.Weight.Kg.t
+}
+```
+
+### Decode an Array written as a String
+
+This codec is intended for encoding the array params of API requests of scala services.
+
+```rescript
+@decco
+type params = {
+  lengths: Toolkit.Decoder.StringArray<Toolkit.Decoder.UnitMeasure.Dimension.WithUnit.t>
+};
+
+let params = {lengths:[#cm(1),#m(40), #km(3)]};
+let encodedParams = params->params_encode; // "1.00 cm,40.00 m,3.00 km"
+let decodedParams = encodedParams->params_decode; // Ok([#cm(1),#m(40),#km(3)])
+```

package/playground/docs/Form.mdx

@@ -0,0 +1,109 @@
+# Handling forms
+
+We have created a fork of [reform@9.8.0](https://github.com/Astrocoders/reform) we had some features :
+
+- `onSubmit` must return a `Promise.promise(result('a, 'e))`
+- `SubmitFailed(option('error'))` to the `formState('error)` variant
+
+## Usage
+
+### Define a FormState
+
+The module must contains an `error` type and an include of `state` type with `%lenses`
+
+```rescript
+module FormState = {
+  type error = ColiswebApi.V5.Store.Contact.CreateContact.Request.error;
+  include [%lenses
+            type state = {
+              firstName: string,
+              lastName: string,
+              email: string,
+              phone1: string,
+              phone2: string,
+            }
+          ];
+};
+
+module FormApi = Toolkit.Form.Make(FormState);
+```
+
+### Use the form in React
+
+```rescript
+// ...
+@react.component
+let make = () => {
+
+  let initialState =
+    FormState.{
+      firstName: "",
+      lastName: "",
+      phone1: "",
+      phone2: "",
+      email: "",
+    };
+
+  let schema =
+    FormApi.Form.Validation.Schema([
+      StringNonEmpty(FirstName),
+      StringNonEmpty(LastName),
+      Email(Email),
+    ]);
+
+  let onSubmit = (form: FormApi.Form.onSubmitAPI) => {
+    let {values}: FormApi.Form.state = form.state;
+
+    ColiswebApi.V5.Store.Contact.CreateContact.Config.exec((
+      clientId,
+      storeId,
+      {
+        firstName: values.firstName->OptionUtils.fromString,
+        lastName: values.lastName->OptionUtils.fromString,
+        email: values.email,
+        phone1: values.phone1->OptionUtils.fromString,
+        phone2: values.phone2->OptionUtils.fromString,
+      },
+    ))
+    ->Promise.flatMapOk(result =>
+        reloadContact()->Promise.map(_ => Ok(result))
+      )
+    ->Promise.tapOk(_ => hide())
+  };
+
+  let form = FormApi.Form.use(~initialState, ~schema, ~onSubmit, ());
+
+  <FormApi.Form.Provider value=form>
+    <form onSubmit={event => {
+        ReactEvent.Synthetic.preventDefault(event);
+        form.submit();
+      }}>
+
+      <Form.Field
+        field
+        render={({handleChange, error, value, validate}) => {
+          let isInvalid = error->Option.isSome;
+          <>
+            <input value onChange={BsReform.Helpers.handleChange(handleChange)} />
+
+            {
+              error->Option.mapWithDefault(React.null, e => <p>e->React.string</p>)
+            }
+          </>;
+        }}
+      />;
+
+      <Button
+        type_="submit"
+        color=#primary
+        isLoading={form.state.formState === Submitting}
+        onClick={_ => form.submit()}>
+        <FormattedMessage
+          id="forms.controls.confirm"
+          defaultMessage="Confirm"
+        />
+      </Button>
+    </form>
+  </FormApi.Form.Provider>;
+}
+```

package/playground/docs/Identifiers.mdx

@@ -0,0 +1,38 @@
+# Avoid string type with unique identifiers
+
+Convert a string or an int in an opaque type with a decco decoder.
+
+### `string` identifier
+
+```rescript
+module DeliveryId = Toolkit.Identifier.MakeString({});
+
+/**
+ somewhere
+**/
+@decco
+type response = {
+  deliveryId: DeliveryId.t
+};
+
+let deliveryId = DeliveryId.make("some-id");
+deliveryId->DeliveryId.toString // "some-id"
+```
+
+### `int` identifier
+
+```rescript
+module DeliveryId = Toolkit.Identifier.MakeInt({});
+
+/**
+ somewhere
+**/
+@decco
+type response = {
+  deliveryId: DeliveryId.t
+};
+
+let deliveryId = DeliveryId.make(12);
+deliveryId->DeliveryId.toString; // "12"
+deliveryId->DeliveryId.toInt; // 12
+```

package/playground/{Doc.res → docs/Playground_Docs.res}

@@ -1,32 +1,32 @@
 module ApiDecoding = {
-  @module("../../../docs/ApiDecoding.mdx") @react.component
+  @module("../../../../playground/docs/ApiDecoding.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Form = {
-  @module("../../../docs/Form.mdx") @react.component
+  @module("../../../../playground/docs/Form.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Identifiers = {
-  @module("../../../docs/Identifiers.mdx") @react.component
+  @module("../../../../playground/docs/Identifiers.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Primitives = {
-  @module("../../../docs/Primitives.mdx") @react.component
+  @module("../../../../playground/docs/Primitives.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Requests = {
-  @module("../../../docs/Request.mdx") @react.component
+  @module("../../../../playground/docs/Request.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Setup = {
-  @module("../../../docs/Setup.mdx") @react.component
+  @module("../../../../playground/docs/Setup.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Router = {
-  @module("../../../docs/Router.mdx") @react.component
+  @module("../../../../playground/docs/Router.mdx") @react.component
   external make: unit => React.element = "default"
 }
 module Unleash = {
-  @module("../../../docs/Unleash.mdx") @react.component
+  @module("../../../../playground/docs/Unleash.mdx") @react.component
   external make: unit => React.element = "default"
 }

package/playground/docs/Primitives.mdx

@@ -0,0 +1,53 @@
+# Primitives
+
+Utililties functions for primitives types :
+
+- `option`
+- `string`
+- `array`
+
+## Option
+
+### string
+
+- `fromString` : `string => option(string)`
+- `toString` : `option(string) => string`
+
+```rescript
+let anEmptyString = "";
+
+Toolkit.Primitives.Option.fromString(anEmptyString)
+->Option.map(v => v ++ "test");
+
+Toolkit.Primitives.Option.toString(Some("test")); // "test"
+Toolkit.Primitives.Option.toString(None); // ""
+```
+
+### boolean
+
+- `fromBool` : `bool => option(bool)`
+
+```rescript
+Toolkit.Primitives.Option.fromBool(true); // Some(true)
+Toolkit.Primitives.Option.fromBool(false); // None
+```
+
+## Array
+
+```rescript
+let variable = ["abc", "dce", ""];
+
+Js.log(Primitives.Array.joinNonEmpty(anEmptyString)); // "abc, dce"
+Js.log(Primitives.Array.joinNonEmpty(~separator="+", anEmptyString)); // "abc+dce"
+Js.log(variable->Primitives.Array.tail); // ""
+```
+
+## Result
+
+```rescript
+let result = Ok("test");
+let test = Error("error");
+
+Js.log(Primitives.Result.get(result)); // Some("test")
+Js.log(Primitives.Result.get(test)); // None
+```

package/playground/docs/Request.mdx

@@ -0,0 +1,281 @@
+# How to manage an API request
+
+## 1. Create the request config
+
+You have to declare 3 types :
+
+- `argument` is what you give to the function
+- `response` is what your API answer
+- `error` is the potential custom errors that can occur (⚠️ this has to be handled manually)
+
+And the `exec` method.
+
+We use [decco](https://github.com/reasonml-labs/decco) to serialize / deserialize the data.
+
+```rescript
+let request = Axios.Instance.create(
+  Axios.makeConfig(~baseURL=envState.apiUrl,()),
+);
+
+module FetchUsers = {
+  module Config = {
+    type argument = unit;
+
+    @decco
+    type response = array<user>
+    @decco
+    and user = {
+      name: string
+    };
+
+    type error = string;
+
+    let exec = () => {
+      request->Request.get("/", response_decode);
+    };
+  };
+  module Request = Toolkit.Request.Make(Config);
+};
+
+FetchUsers.Request.exec();
+```
+
+### 1.2 Send data
+
+We create a decodable `body` type that we give to the `argument` type.
+This decodable `body` will be used in the exec method.
+
+```rescript
+module UpdateUser = {
+  module Config = {
+    type argument = body
+    @decco
+    and body = {
+      name: string,
+    };
+
+    @decco
+    type response = unit;
+
+    type error = unit;
+
+    let exec = body => {
+      request->Request.postData("/update-user", response_decode, body->body_encode);
+    };
+  };
+  module Request = Toolkit_Request.Make(Config);
+};
+
+UpdateUser.Request.exec({ name: "test" })
+```
+
+### 1.3 Handle errors
+
+In order to handle special errors comming from the API, you can use the `mapError` parameter.
+
+This parameter requires a callback which contains the **response** as argument and needs to return this type :
+
+```rescript
+option<result<'data, error<'a>>>
+```
+
+The `result` is useful for some cases when an API error should not break the flow so you can handle the specific error and just return `Ok()`.
+
+#### Request error type
+
+```rescript
+type undecodedResponse = {
+  data: undecodedData,
+  headers,
+  config,
+  status: int,
+};
+
+type noResponse = {
+  message: string,
+  config,
+};
+
+// We get this type in mapError callback argument
+type failedResponse = {
+  message: string,
+  config,
+  response,
+}
+and response = {
+  data: failedResponseData,
+  headers,
+  status: int,
+};
+
+type error<'a> = [
+  | #noResponse(noResponse)
+  | #invalidResponse(failedResponse)
+  | #invalidResponseData(undecodedResponse, string)
+  | #invalidErrorData
+  | #unknown(Js.Promise.error)
+  | #custom('a)
+]
+```
+
+```rescript
+let exec = token => {
+  request->Request.get(
+    "/test",
+    ~mapError=
+      error => {
+        // have to return option(Toolkit.Request.error('a'))
+      },
+    response_decode,
+  );
+};
+```
+
+`failedResponseData` can be anything depending on the API behavior. So you have to use `Obj.magic` to cast and use the correct field.
+
+```rescript
+let handleError = (error: failedResponse) => {
+  // the API return an object { code: string }
+  let code = error.response.data->Obj.magic##code;
+
+  // If code can be undefined
+  code
+  ->Option.map(code => {
+    switch (code) {
+      | "some_code" => Error(#custom("message"))
+      | "other_code" => Error(#invalidErrorData)
+      | "its_ok" => Ok()
+      | _ => Error(#custom("unknown"))
+    }
+  })
+};
+```
+
+Often, we use decco in order to handle complex error (error with data). We create a custom Decoder for this kind of case
+
+```rescript
+module UpdateUser = {
+  module Config = {
+    type argument = body
+    @decco
+    and body = {name: string};
+
+    @decco
+    type response = unit;
+
+    module Error =
+      Decoders.Enum({
+        @deriving(jsConverter)
+        type enum = [
+          | #"unknown-user"
+          | #invalidData
+          | #unknownError
+        ];
+      });
+
+    @decco
+    type error = Error.t;
+
+    let exec = body => {
+      request->Request.postData(
+        "/update-user",
+        response_decode,
+        body->body_encode,
+        ~mapError=
+          ({response}) => {
+            switch (response.data->Obj.magic->error_decode) {
+            | Ok(error) => Some(Error(`custom(error)))
+            | Error(err) =>
+              Js.log(err);
+              Some(Error(`custom(`unknownError)));
+            }
+          }
+      );
+    };
+  };
+  module Request = Toolkit_Request.Make(Config);
+};
+
+UpdateUser.Request.exec({ name: "test" })
+->Promise.tapError(err => {
+  switch (err) {
+    | #custom(#"unknown-user") => Js.log("user not found")
+    | #custom(#unknownError) => Js.log("alert sentry")
+    | _ => Js.log("generic handler")
+  }
+})
+```
+
+## 2. Use request in React
+
+### 2.1 Fetching data with swr
+
+There are several ways to manage a request in React, we chose to use [swr](https://swr.vercel.app/) with [react-suspense](https://reactjs.org/docs/concurrent-mode-suspense.html) enabled.
+We have a functor to generate automaticatly a swr fetcher based on the request created before :
+
+```rescript
+module GetUsers = {
+  module Config = {
+    type argument = unit;
+
+    @decco
+    type response = array<user>
+    @decco
+    and user = {
+      name: string
+    };
+
+    type error = string;
+
+    let exec = () => {
+      request->Request.get("/users", response_decode);
+    };
+  };
+  module Request = Toolkit.Request.Make();
+};
+
+
+module GetUsersFetcher =
+  Fetcher.Make({
+    module Request = GetUsers.Request;
+    let key = () => [|
+      "GetUsers",
+    |];
+  });
+```
+
+Later in the react app
+
+```rescript
+module PageUsers = {
+  [@react.component]
+  let make = () => {
+    let (users, _, _) = GetUsersFetcher.use();
+
+    <div>
+      {
+        users
+        ->Belt.Array.mapWithIndex((i, user) => {
+          <div key={i->Belt.Int.toString}>
+            {user.name->React.String}
+          </div>
+        })
+      }
+    </div>
+  };
+};
+
+[@react.component]
+let make = () => {
+  <ErrorBoundary>
+    <React.Suspense fallback={<Spinner />}>
+      <PageUsers />
+    </React.Suspense>
+  </ErrorBoundary>
+};
+```
+
+There are 2 functions generated by the fetcher functor :
+
+- `use` can be used when the API will always return something
+- `useOptional` return an `option<'a>` so it's used when the API can return nothing

package/playground/docs/Router.mdx

@@ -0,0 +1,43 @@
+# Router
+
+Type-safe navigation
+
+## Usage
+
+```rescript
+open Toolkit
+
+module StoreId = Identifiers.MakeString()
+
+module RouterConfig = {
+  type admin = Home
+
+  type t =
+    | Home
+    | StoreDetails(StoreId.t)
+    | Admin(admin)
+    | NotFound
+
+  let make = url =>
+    switch url.path {
+    | list{} => Home
+    | list{"stores", storeId} => StoreDetails(StoreId.make(storeId))
+    | list{"admin", ...rest} =>
+      switch rest {
+      | list{} => Admin(Home)
+      | _ => NotFound
+      }
+    | _ => NotFound
+    }
+
+  let toString = route =>
+    switch route {
+    | Home => ""
+    | StoreDetails(storeId) => "/stores/" ++ storeId->StoreId.toString
+    | Admin(Home) => "/admin/"
+    | NotFound => "/404"
+    }
+}
+
+module Navigation = Router.Make(RouterConfig)
+```