@reykjavik/webtools 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.13
+
+_2024-03-06_
+
+- feat: Add `@reykjavik/webtools/fixIcelandicLocale` polyfill module
+
 ## 0.1.12
 
 _2024-02-29_

package/CookieHubConsent.d.ts

@@ -218,14 +218,14 @@ export type CookieHubProviderProps = EitherObj<{
  * management script and sets up a React state object with the relevant user
  * consent flags.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##cookiehubprovider-component
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cookiehubprovider-component
  */
 export declare const CookieHubProvider: (props: CookieHubProviderProps) => React.JSX.Element;
 /**
  * Returns up-to-date cookie consent flags. For use in React components or hook
  * functions.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##usecookiehubconsent
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#usecookiehubconsent
  */
 export declare const useCookieHubConsent: () => Partial<CookieHubContextState['consent']>;
 export {};

package/CookieHubConsent.js

@@ -61,7 +61,7 @@ const moveCookiehubScriptInDomTree = () => {
  * management script and sets up a React state object with the relevant user
  * consent flags.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##cookiehubprovider-component
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cookiehubprovider-component
  */
 const CookieHubProvider = (props) => {
     const [state, setState] = (0, react_1.useState)(initialConsentState);
@@ -134,7 +134,7 @@ exports.CookieHubProvider = CookieHubProvider;
  * Returns up-to-date cookie consent flags. For use in React components or hook
  * functions.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##usecookiehubconsent
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#usecookiehubconsent
  */
 const useCookieHubConsent = () => { var _a; return ((_a = (0, react_1.useContext)(CookieHubContext)) === null || _a === void 0 ? void 0 : _a.consent) || {}; };
 exports.useCookieHubConsent = useCookieHubConsent;

package/README.md

@@ -12,7 +12,7 @@ yarn add @reykjavik/webtools
 bun add @reykjavik/webtools
 ```
 
-**Table of Contents:**
+**Contents:**
 
 <!-- prettier-ignore-start -->
 
@@ -22,27 +22,22 @@ bun add @reykjavik/webtools
   - [`cacheControl` helper](#cachecontrol-helper)
     - [Type `TTLConfig`](#type-ttlconfig)
   - [`toSec` TTL helper](#tosec-ttl-helper)
-- [`@reykjavik/webtools/next/http`](#reykjavikwebtoolsnexthttp)
-  - [`makeErrorizeAppHOC`](#makeerrorizeapphoc)
-  - [`showErrorPage` helper](#showerrorpage-helper)
-  - [`notModified304` helper](#notmodified304-helper)
 - [`@reykjavik/webtools/CookieHubConsent`](#reykjavikwebtoolscookiehubconsent)
   - [`CookieHubProvider` component](#cookiehubprovider-component)
   - [`useCookieHubConsent`](#usecookiehubconsent)
-- [`@reykjavik/webtools/next/SiteImprove`](#reykjavikwebtoolsnextsiteimprove)
-  - [`SiteImprove` component](#siteimprove-component)
-  - [`pingSiteImprove` helper](#pingsiteimprove-helper)
-  - [`pingSiteImproveOutbound` helper](#pingsiteimproveoutbound-helper)
 - [`@reykjavik/webtools/vanillaExtract`](#reykjavikwebtoolsvanillaextract)
   - [`vanillaGlobal`](#vanillaglobal)
   - [`vanillaProps`](#vanillaprops)
   - [`vanillaClass`](#vanillaclass)
   - [`vanillaClassNested`](#vanillaclassnested)
   - [`vanillaNest`](#vanillanest)
+- [`@reykjavik/webtools/fixIcelandicLocale`](#reykjavikwebtoolsfixicelandiclocale)
+- [Framework Specific Tools](#framework-specific-tools)
+  - [Next.js Tools](#nextjs-tools)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
 
-<!-- prettier-ignore-start -->
+<!-- prettier-ignore-end -->
 
 ---
 
@@ -184,165 +179,6 @@ const ttlSec = toSec(ttl);
 
 ---
 
-## `@reykjavik/webtools/next/http`
-
-Contains HTTP helpers for Next.js projects
-
-Re-exports all of the base [http module](#reykjaviktoolshttp)'s exports, for
-convenience
-
-### `makeErrorizeAppHOC`
-
-**Syntax:**
-`makeErrorizeAppHOC(ErrorPageComponent: ComponentType<EP>): (App: AppType<P>) => AppType<P | EP>`
-
-Hhigher-order component (HOC) factory for Next.js App compnents to handle
-cases when `getServerSideProps` returns an `__error` prop with `statusCode`
-and optional friendly `message`.
-
-Pass in an error-page compnent, and receive a HOC function that wraps any
-Next.js App compnent. The HOC also has a type-safe
-[`.showErrorPage`](#showerrorizedpage-helper) helper method to use inside
-`getServerSideProps` in order to trigger display of the error page.
-
-Set up the error page for your app:
-
-```tsx
-// src/helpers/myerrors.js
-
-import {
-  makeErrorizeAppHOC,
-  ErrorProps,
-  InferErrorPageProps,
-} from '@reykjavik/webtools/next/http';
-
-type MyErrorPageProps = ErrorProps & {
-  /* ...custom props... */
-};
-const MyErrorPage = (props: MyErrorPageProps) => {
-  const { statusCode, message /* plus your custom props */ } = props;
-  return (
-    <div>
-      <h1>{statusCode}</h1>
-      {message && <p>{message}</p>}
-    </div>
-  );
-};
-
-// Generate and export the HOC
-export const withMyErrorHandling = makeErrorizeAppHOC(MyErrorPage);
-// Export the gSSP helper
-export const showErrorPage = withMyErrorHandling.showErrorPage;
-// Export the props type of the error page
-export type ErrorPageProps = InferErrorPageProps<typeof showErrorPage>;
-```
-
-Wrap `_app.tsx` with the HOC you generated:
-
-```jsx
-// src/pages/_app.js
-
-import { withMyErrorHandling } from '~/helpers/myerrors';
-
-const App = ({ Component, pageProps }: AppProps<PageProps>) => {
-  // ...define your App component as normal...
-};
-
-export default withMyErrorHandling(App);
-```
-
-Return errors inside your page/route modules, using `showErrorPage`
-
-```tsx
-// src/pages/index.js
-
-import type { GetServerSideProps } from 'next';
-import { showErrorPage, ErrorPageProps } from '~/helpers/errors';
-
-type MyPageProps = {};
-// Export the page component
-export default function MyPage(props: MyPageProps) {
-  // ...
-}
-
-export const getServerSideProps: GetServerSideProps<
-  MyPageProps | ErrorPageProps
-> = async (ctx) => {
-  // ...fetch data from api
-  if (!apiRes.error === 'unauthorized') {
-    return showErrorPage(ctx.res, {
-      statusCode: HTTP_400_BadRequest,
-      // ...Add other custom MyErrorPage props
-    });
-  }
-  // ...return normal, happy page props.
-};
-```
-
-See more below
-
-### `showErrorPage` helper
-
-**Syntax:**
-`showErrorPage = (response: ServerResponse | NextContext, error: HTTP_ERROR | ErrorProps, ttl?: TTL | TTLConfig): void`
-
-This method is attached to the HOC returned by
-[`makeErrorizeAppHOC`](#makeerrorizeapphoc). Use it inside your pages'
-`getServerSideProps` to return the appropriate an "error" props, including a
-HTTP `statusCode`, etc.
-
-```js
-import { showErrorPage, ErrorPageProps } from '~/helpers/myerrors';
-
-// ...then, somewhere inside getServerSideProps
-if (invalidParams) {
-  return showErrorPage(
-    res,
-    {
-      statusCode: HTTP_400_BadRequest,
-      message: 'You passed me bad params :-(', // optional message
-      // ...Add other custom MyErrorPage props
-    },
-    'permanent'
-  );
-}
-
-if (!apiRes.error === 'unauthorized') {
-  // Optional `statusCode` shorthand signature, available if your
-  // error page has no required props (other than `statusCode`).
-  return showErrorPage(res, HTTP_403_Forbidden);
-}
-
-// ...return normal, happy page props.
-```
-
-The `ttl` parameter defaults to `'2s'`, but you can pass any
-[`TTLConfig`](#type-ttlconfig).
-
-### `notModified304` helper
-
-**Syntax:** `notModified304(response: ServerResponse | NextContext): void`
-
-Use this method to inside a `getServerSideProps` method (or API route) to
-return a `HTTP_304_NotModified` response with an empty props object, in a way
-that doesn't make TypeScript shout at you.
-
-(Turns out that when a 304 status is returned, then Next.js doesn't even
-attempt to render the Page compnoent, so the returned props don't matter.
-TypeScript, however, doesn't know that.)
-
-```js
-import { notModified304 } from '@reykjavik/webtools/next/http';
-
-// ...then, somewhere inside getServerSideProps
-const notModified = data.modifiedTimestamp === req.headers['if-none-match'];
-if (notModified) {
-  return notModified304(res);
-}
-```
-
----
-
 ## `@reykjavik/webtools/CookieHubConsent`
 
 Contains React helpers for loading CookieHub's consent manager and reading
@@ -416,98 +252,6 @@ this hook will return an empty object.
 
 ---
 
-## `@reykjavik/webtools/next/SiteImprove`
-
-Contains React helpers for loading SiteImprove's analytics scripts in Next.js
-applications and perform custom event tracking.
-
-### `SiteImprove` component
-
-A component for loading a SiteImprove analytics script and set up page-view
-tracking across Next.js routes.
-
-It also automatically logs all out-bound link clicks.
-
-Example usage in pages/\_app.tsx
-
-```js
-import { SiteImprove } from '@reykjavik/webtools/next/SiteImprove';
-
-const siteImproveAccountId = '[ACCOUNT_ID]'; // e.g. "7654321"
-
-// Inside MyApp component
-<Component {...pageProps} />
-<SiteImprove
-  accountId={siteImproveAccountId}
-  onError={(error) =>
-    Logger('error', 'An error occured initializing siteimprove', error)
-  }
-/>;
-```
-
-The component has an optional `hasConsented` prop which can be used to
-forcefully suppress loading the analytics script.
-
-In dev mode it does NOT load the SiteImprove script and only logs page-view
-events to the console.
-
-**Props:**
-
-The Component's props have detailed JSDoc comments (displayed in your code
-editor), but there's a brief summary:
-
-- `accountId?: string` — Your SiteImprove account ID. (alternative to
-  `scriptUrl` prop).
-- `scriptUrl?: string` — The full SiteImprove analytics script URL.
-  (alternative to `accountId` prop).
-- `hasConstented?: boolean` — Manual GDPR 'analytics' consent flag. Allows
-  hard opt-out, but defers to
-  [`CookieHubProvider` values](#usecookiehubconsent) if they are available.
-- `onLoad?: (e: unknown) => void` — Fires when the script has loaded.
-- `onError?: (e: unknown) => void` — Fires if loading the script failed.
-
-### `pingSiteImprove` helper
-
-**Syntax:**
-`pingSiteImprove(category: string, action: string, label?: string): void`
-
-A small helper for tracking custom UI events and reporting them to SiteImrove.
-
-It safely manages GDPR consent, so you can use it unconditionally.
-
-```js
-import { pingSiteImprove } from '@reykjavik/webtools/next/SiteImprove';
-
-const handleSubmit = () => {
-  // perform submit action...
-  if (success) {
-    pingSiteImprove('application', 'add_new');
-  }
-};
-```
-
-### `pingSiteImproveOutbound` helper
-
-**Syntax:** `pingSiteImproveOutbound(ourl: string): void`
-
-A small helper for reporting to SiteImrove when the user is programmatically
-being sent to a different URL/resource.
-
-```js
-import { pingSiteImproveOutbound } from '@reykjavik/webtools/next/SiteImprove';
-
-const handleSubmit = () => {
-  // perform submit action...
-  if (success) {
-    const fileUrl = '/download/report.pdf';
-    pingSiteImproveOutbound(fileUrl);
-    document.location.href = fileUrl;
-  }
-};
-```
-
----
-
 ## `@reykjavik/webtools/vanillaExtract`
 
 Contains helpers for writing [vanilla-extract](https://vanilla-extract.style)
@@ -525,6 +269,7 @@ CSS.
 Inserts free-form CSS as a vanilla-extract `globalStyle`.
 
 ```ts
+// someFile.css.ts
 import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
 
 vanillaGlobal(`
@@ -542,6 +287,7 @@ Spreads the return value into a style object, to inject free-form CSS
 properties (or nested blocks)
 
 ```ts
+// someFile.css.ts
 import { style } from '@vanilla-extract/css';
 import { vanillaProps } from '@reykjavik/webtools/vanillaExtract';
 
@@ -567,6 +313,7 @@ Returns a scoped cssClassName styled with free-form CSS. This function is a
 thin wrapper around vanilla-extract's `style` function.
 
 ```ts
+// someFile.css.ts
 import { vanillaClass } from '@reykjavik/webtools/vanillaExtract';
 
 export const myClass = vanillaClass(`
@@ -594,6 +341,7 @@ It also automatically replaces all `&`-tokens with the selector for the
 auto-generated class-name.
 
 ```ts
+// someFile.css.ts
 import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
 
 export const myClass = vanillaClassNested(`
@@ -629,13 +377,18 @@ comments, etc. If you need something more sophisticated, use a custom
 Replaces all `&` tokens with the given selector string, in a direct (read.
 "dumb") way. It's mainly useful when used with style-mixins, etc.
 
-This low-level utility function is used internally by
-[`vanillaClassNested`](#vanillaclassnested).
+`vanillaNest` does NOT support deeply nested blocks, or anything so fancy. It
+will also replace `&` characters inside values, comments, etc. If you need
+something more sophisticated, use a custom `postcss` config.
 
 ```ts
+// someCssHelper.ts
 import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
 
-const hoverGlow = (ampSelector: string, glowiness?: 'normal' | 'insane') =>
+export const hoverGlow = (
+  ampSelector: string,
+  glowiness?: 'normal' | 'insane'
+) =>
   vanillaNest(
     ampSelector,
     `
@@ -647,8 +400,9 @@ const hoverGlow = (ampSelector: string, glowiness?: 'normal' | 'insane') =>
   `
   );
 
-// ...then, somewhere else
+// ...then, somewhere else in a *.css.ts file:
 
+import { hoverGlow } from '~/someCssHelper.js';
 import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
 
 vanillaGlobal(`
@@ -666,9 +420,49 @@ vanillaGlobal(`
 `);
 ```
 
-**NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything so
-fancy. It will also replace `&` characters inside values, comments, etc. If
-you need something more sophisticated, use a custom `postcss` config.
+(This low-level utility function is used internally by
+[`vanillaClassNested`](#vanillaclassnested).)
+
+---
+
+## `@reykjavik/webtools/fixIcelandicLocale`
+
+Polyfill for `String.prototype.localeCompare` to provide support for the
+`'is'` locale in browsers that don't support it (\*cough* Chrome \*cough*).
+
+At the top of your app's entry point, "side-effect import" this module to
+apply the polyfill:
+
+```ts
+import '@reykjavik/webtools/fixIcelandicLocale';
+
+// Then continue with your day
+// and use `localeCompare` as you normally would...
+```
+
+**NOTE** The polyfill is only applied in engines that fail a simple feature
+test.
+
+---
+
+## Framework Specific Tools
+
+---
+
+<!-- #fragment anchors to not break older v0.1 @see links -->
+
+<a name="reykjavikwebtoolsnexthttp"></a> <a name="makeerrorizeapphoc"></a>
+<a name="showerrorpage-helper"></a> <a name="notmodified304-helper"></a>
+<a name="reykjavikwebtoolsnextsiteimprove"></a>
+<a name="siteimprove-component"></a> <a name="pingsiteimprove-helper"></a>
+<a name="pingsiteimproveoutbound-helper"></a>
+
+### Next.js Tools
+
+This package contains some helpers and components that are specifically
+designed for use in [Next.js](https://nextjs.org/) projects.
+
+See [README-nextjs.md](README-nextjs.md) for more info.
 
 ---
 
@@ -677,7 +471,7 @@ you need something more sophisticated, use a custom `postcss` config.
 This project uses the [Bun runtime](https://bun.sh) for development (tests,
 build, etc.)
 
-PRs are welcoms!
+PRs are welcome!
 
 ---
 
@@ -685,11 +479,3 @@ PRs are welcoms!
 
 See
 [CHANGELOG.md](https://github.com/reykjavikcity/webtools/blob/main/CHANGELOG.md)
-
-```
-
-```
-
-```
-
-```

package/esm/CookieHubConsent.d.ts

@@ -218,14 +218,14 @@ export type CookieHubProviderProps = EitherObj<{
  * management script and sets up a React state object with the relevant user
  * consent flags.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##cookiehubprovider-component
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cookiehubprovider-component
  */
 export declare const CookieHubProvider: (props: CookieHubProviderProps) => React.JSX.Element;
 /**
  * Returns up-to-date cookie consent flags. For use in React components or hook
  * functions.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##usecookiehubconsent
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#usecookiehubconsent
  */
 export declare const useCookieHubConsent: () => Partial<CookieHubContextState['consent']>;
 export {};

package/esm/CookieHubConsent.js

@@ -35,7 +35,7 @@ const moveCookiehubScriptInDomTree = () => {
  * management script and sets up a React state object with the relevant user
  * consent flags.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##cookiehubprovider-component
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#cookiehubprovider-component
  */
 export const CookieHubProvider = (props) => {
     const [state, setState] = useState(initialConsentState);
@@ -107,6 +107,6 @@ export const CookieHubProvider = (props) => {
  * Returns up-to-date cookie consent flags. For use in React components or hook
  * functions.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1##usecookiehubconsent
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#usecookiehubconsent
  */
 export const useCookieHubConsent = () => { var _a; return ((_a = useContext(CookieHubContext)) === null || _a === void 0 ? void 0 : _a.consent) || {}; };

package/esm/fixIcelandicLocale.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/fixIcelandicLocale.js

@@ -0,0 +1,21 @@
+const locAliases = {
+    // Danish is good enough substitution for Icelandic
+    is: 'da',
+    'is-is': 'da',
+};
+const mapLocales = (locales) => {
+    locales = typeof locales === 'string' ? [locales] : locales || [];
+    return locales.map((loc) => locAliases[loc.toLowerCase()] || loc);
+};
+// ---------------------------------------------------------------------------
+if ( /*#__PURE__*/'ö'.localeCompare('p', 'is') < 0) {
+    const _localeCompare = String.prototype.localeCompare;
+    /**
+     * Polyfill for String.prototype.localeCompare for the 'is' locale
+     * in browsers that don't support it (\*cough* Chrome \*cough*).
+     */
+    String.prototype.localeCompare = function (that, locales, options) {
+        return _localeCompare.call(this, that, mapLocales(locales), options);
+    };
+}
+export {};

package/esm/http.d.ts

@@ -153,21 +153,21 @@ type TTLObj = {
 /**
  * Configures quick TTL-related settings for a HTTP request object
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1#type-ttlconfig
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-ttlconfig
  */
 export type TTLConfig = TTL | TTLKeywords | TTLObj;
 /**
  * Converts a `TTL` (max-age) value into seconds, and returns `0` for bad
  * and/or negative input values.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1#tosec-ttl-helper
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#tosec-ttl-helper
  */
 export declare const toSec: (ttl: TTL) => number;
 /**
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1#getcssbundleurl
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#getcssbundleurl
  */
 export declare const cacheControl: (response: ServerResponse | {
     res: ServerResponse;

package/esm/http.js

@@ -136,7 +136,7 @@ const unitToSeconds = {
  * Converts a `TTL` (max-age) value into seconds, and returns `0` for bad
  * and/or negative input values.
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1#tosec-ttl-helper
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#tosec-ttl-helper
  */
 export const toSec = (ttl) => {
     if (typeof ttl === 'string') {
@@ -168,7 +168,7 @@ const setCC = (response, cc) => {
  * Use this function to quickly set the `Cache-Control` header with a `max-age=`
  * on a HTTP response
  *
- * @see https://github.com/reykjavikcity/webtools/tree/v0.1#getcssbundleurl
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#getcssbundleurl
  */
 // eslint-disable-next-line complexity
 export const cacheControl = (response, ttlCfg, eTag) => {

package/esm/index.d.ts

@@ -1,5 +1,6 @@
 /// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
+/// <reference path="./fixIcelandicLocale.d.ts" />
 /// <reference path="./CookieHubConsent.d.tsx" />
 /// <reference path="./next/SiteImprove.d.tsx" />
 /// <reference path="./next/http.d.tsx" />