@bigbinary/neeto-molecules 5.3.17 → 5.3.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigbinary/neeto-molecules",
-  "version": "5.3.17",
+  "version": "5.3.19",
   "description": "A package of reusable molecular components for neeto products.",
   "repository": "git@github.com:bigbinary/neeto-molecules.git",
   "author": "Amaljith K <amaljith.k@bigbinary.com>",

package/types/BrowserSupport.d.ts

@@ -4,6 +4,19 @@ type VersionLimits = {
   softLimit?: number;
   hardLimit?: number;
 };
+type BrowserVersionOverrides = {
+  Chrome?: VersionLimits;
+  MobileChrome?: VersionLimits;
+  Edge?: VersionLimits;
+  Firefox?: VersionLimits;
+  MobileFirefox?: VersionLimits;
+  Safari?: VersionLimits;
+  MobileSafari?: VersionLimits;
+  Opera?: VersionLimits;
+  SamsungInternet?: VersionLimits;
+  Electron?: VersionLimits;
+  WebKit?: VersionLimits;
+};
 /**
  *
  * A wrapper that displays a callout message for partially supported browsers
@@ -29,59 +42,142 @@ type VersionLimits = {
  *   <Main />
  * )
  * @endexample
- * Minimum supported browser version of a specific browser can be changed using the
+ * This placement handles browsers that load the app but cannot render it properly.
+ *
+ * It cannot help when the browser is too old to parse the app chunk at all — see
+ *
+ * the next section, which is the placement most products actually want.
+ *
+ * Wrapping Main in <BrowserSupport> cannot help when the browser is old enough
+ *
+ * that the app chunk fails to parse. mount() rejects on the dynamic import and
+ *
+ * React never renders, so the user gets a blank page rather than an explanation.
  *
- * overrides prop like so:
+ * For that case call renderBrowserSupportGate from the pack, before mount(),
+ *
+ * where only the entry chunk has had to parse. It returns true when the browser
+ *
+ * was blocked, meaning the app must not be mounted:
+ *
+ * @example 
+ *
+ * import mount from "neetocommons/react-utils/mount";
+ * import { renderBrowserSupportGate } from "@bigbinary/neeto-molecules/v2/BrowserSupport";
+ * 
+ * const initializeAndMount = async () => {
+ *   await initializeApplication();
+ * 
+ *   if (renderBrowserSupportGate()) return;
+ * 
+ *   mount(componentMap);
+ * };
+ * @endexample
+ * It renders into [data-react-class] by default, the same element mount()
+ *
+ * uses; pass element to override. When it blocks it also removes
+ *
+ * #neeto-page-loader, the loader rendered by shared/_page_loader in
+ *
+ * neeto-commons-backend, which sits outside the react root and would otherwise
+ *
+ * keep spinning over the message; pass loaderSelector if your product renders a
+ *
+ * different one. overrides and unsupportedBrowsers behave as they do on the
+ *
+ * component, and products should not normally need either — the defaults are the
+ *
+ * floor the shared stack imposes, so a product that overrides them is opting out
+ *
+ * of the guarantee rather than configuring it. Whatever the pack imports has to
+ *
+ * stay parseable on the browsers being guarded against, so keep the entry chunk
+ *
+ * free of syntax newer than the floor you are enforcing.
+ *
+ * The overrides prop changes the limits for a specific browser. The usual reason
+ *
+ * to reach for it is to open a partial band, where a browser below softLimit but
+ *
+ * at or above hardLimit gets a callout and still sees the page:
  *
  * @example 
  *
  * <BrowserSupport
  *   overrides={{
- *     Chrome: { softLimit: 80, hardLimit: 60 },
- *     Safari: { softLimit: 14.1, hardLimit: 13.5 },
+ *     Chrome: { softLimit: 120, hardLimit: 111 },
+ *     Safari: { softLimit: 17, hardLimit: 16.4 },
  *   }}
- *   unsupportedBrowsers={["Firefox"]}
+ *   unsupportedBrowsers={["SamsungInternet"]}
  * />
  * @endexample
- * In the above code we have changed the minimum supported versions of Chrome &
+ * Here Chrome 111 to 119 and Safari 16.4 to 16.6 get the callout along with the
  *
- * Safari. Now if a user has accessed the site using Chrome < 80 or Safari < 14.1
+ * page contents. Chrome below 111 and Safari below 16.4 get the full-page message
  *
- * the callout message will be displayed. If a user has accessed the site using
+ * and no content. Every version of Samsung Internet is blocked outright.
  *
- * Chrome < 60 or Safari < 13.5, a message will be displayed to update the browser
+ * Lowering hardLimit below the defaults is possible but rarely a good idea. The
  *
- * and page contents will not be shown. If a user has accessed the site using any
+ * defaults are the point at which the generated CSS stops applying, so lowering
  *
- * version of Firefox, a message will be displayed that the browser is unsupported
+ * them serves a visibly broken page instead of a message explaining why.
  *
- * and page contents will not be shown.
+ * The default minimum versions are set by Tailwind v4, which hardcodes its
  *
- * The default supported browser names and their versions are given below:
+ * Lightning CSS targets to Safari/iOS 16.4, Chrome 111 and Firefox 128 and exposes
  *
- * | Browser Name    | Min Supported version |
+ * no option to lower them. Below that floor the generated CSS (@property,
+ *
+ * oklch(), :has(), @container) is dropped by the parser without an error, so
+ *
+ * the app renders broken rather than degraded. The remaining engines are pinned to
+ *
+ * the first release built on an equivalent core.
+ *
+ * | Browser name    | Min supported version |
  *
  * | :-------------- | :-------------------- |
  *
- * | Chrome          | 79                    |
+ * | Chrome          | 111                   |
+ *
+ * | MobileChrome    | 111                   |
  *
- * | Firefox         | 91                    |
+ * | Edge            | 111                   |
  *
- * | IE              | 11                    |
+ * | Firefox         | 128                   |
  *
- * | Opera           | 73                    |
+ * | MobileFirefox   | 128                   |
  *
- * | Safari          | 12.2                  |
+ * | Safari          | 16.4                  |
  *
- * | ChromeMobile    | 105                   |
+ * | MobileSafari    | 16.4                  |
  *
- * | FirefoxMobile   | 104                   |
+ * | Opera           | 98                    |
  *
- * | UCBrowser       | 13.4                  |
+ * | SamsungInternet | 22                    |
  *
- * | SamsungInternet | 4                     |
+ * | Electron        | 24                    |
  *
- * The default unsupported browsers are given below:
+ * | WebKit          | 605                   |
+ *
+ * softLimit and hardLimit are equal by default, so a browser below the floor
+ *
+ * gets the full-page message rather than a callout. There is no meaningful
+ *
+ * "degraded but usable" band below it — the CSS either applies or it does not. Set
+ *
+ * an explicit overrides entry if a product wants a partial band.
+ *
+ * Safari freezes the WebKit build number in its user agent (605.1.15 since
+ *
+ * Safari 12), so the WebKit entry cannot discriminate versions. It exists only
+ *
+ * to keep generic WebKit clients out of the unknown-browser branch.
+ *
+ * The default unsupported browsers are given below. These cannot reach the floor
+ *
+ * at any released version, and are blocked before overrides are consulted:
  *
  * Any other browser which is not in the above lists will be considered as unknown
  *
@@ -89,22 +185,15 @@ type VersionLimits = {
  *
 */
 declare const BrowserSupport: React.FC<{
-  overrides?: {
-    Chrome?: VersionLimits;
-    Edge?: VersionLimits;
-    Firefox?: VersionLimits;
-    IE?: VersionLimits;
-    Opera?: VersionLimits;
-    Safari?: VersionLimits;
-    AndroidBrowser?: VersionLimits;
-    OperaMini?: VersionLimits;
-    MobileChrome?: VersionLimits;
-    MobileFirefox?: VersionLimits;
-    UCBrowser?: VersionLimits;
-    SamsungInternet?: VersionLimits;
-  };
+  overrides?: BrowserVersionOverrides;
   unsupportedBrowsers?: string[];
   children?: React.ReactNode | React.ReactNode[];
 }>;
+declare const renderBrowserSupportGate: (options?: {
+  overrides?: BrowserVersionOverrides;
+  unsupportedBrowsers?: string[];
+  element?: HTMLElement | null;
+  loaderSelector?: string;
+}) => boolean;
 
-export { BrowserSupport as default };
+export { BrowserSupport as default, renderBrowserSupportGate };