@warp-ds/elements 2.2.0-next.2 → 2.2.0-next.20

package/README.md

@@ -14,64 +14,264 @@ start by reviewing the [contributing guidelines](CONTRIBUTING.md).
 
 ### Installation
 
-Install by using npm/pnpm or by adding a script link:
+Warp custom elements are supplied by the Eik CDN. 
+In addition, you can install the `@warp-ds/elements` package to get intellisense
+in your editor.
 
-#### Install using npm
+#### Step 1.
+
+Add the following script and style to the very top of your document head to ensure performant loading
+
+```html
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/elements/2.2.0-next.13/styles.css" crossorigin />
+<script src="https://assets.finn.no/pkg/@warp-ds/elements/2.2.0-next.13/index.js" type="module"></script>
+```
+
+#### Step 2.
+
+Be sure to preload whichever brand fonts you need for a page and load the correct font file:
+
+```html
+<!-- Finn example -->
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/FINNTypeAlleTegn-Light.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/FINNTypeAlleTegn-Medium.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/finn-no.css" crossorigin>
+```
+
+```html
+<!-- Tori example -->
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/ToriSans-Regular.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/ToriSans-Bold.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/ToriSans-Italic.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/tori-fi.css" crossorigin>
+```
+
+```html
+<!-- DBA example -->
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/ProximaNova-Regular.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/ProximaNova-Bold.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/dba-dk.css" crossorigin>
+```
+
+```html
+<!-- Blocket example -->
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/BlocketSans-Regular.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/BlocketSans-Bold.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/BlocketSans-Medium.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/fonts/v1/blocket-se.css" crossorigin>
+```
+
+#### Step 3.
+
+You'll also want to load Warp tokens and resets CSS files to ensure consistent and correct styling for the brand.
+
+```html
+<!-- Finn example -->
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/tokens/finn-no.css" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/resets.css" crossorigin>
+```
+
+```html
+<!-- Tori example -->
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/tokens/tori-fi.css" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/resets.css" crossorigin>
+```
+
+```html
+<!-- DBA example -->
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/tokens/dba-dk.css" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/resets.css" crossorigin>
+```
+
+```html
+<!-- Blocket example -->
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/tokens/blocket-se.css" crossorigin>
+<link rel="stylesheet" href="https://assets.finn.no/pkg/@warp-ds/css/v2/resets.css" crossorigin>
+```
+
+#### Step 4.
+
+Next, to add intellisense to your editor install `@warp-ds/elements` by using npm/pnpm. See the Editor integration below.
+
+##### Install using npm
 
 ```sh
 npm install @warp-ds/elements
 ```
 
-#### Install using pnpm
+##### Install using pnpm
 
 ```sh
 pnpm add @warp-ds/elements
 ```
 
-#### Using a direct link to Eik
+And then head on down to the editor configuration section below to complete setup.
+
+### Using Warp elements with Borealis
+
+If you are using Borealis modules from the Web Platform Team (and you should be) and keeping your app dependencies up to date (and you should be), then steps 2 and 3 are already taken care of for you, you just need to do steps 1 and 4.
+
+### Documentation
+
+For information on the components available in the package and how to use them,
+see the [Warp Design System documentation](https://warp-ds.github.io/tech-docs/).
+
+### Editor integration
+
+#### Typescript
+
+Install the `@warp-ds/elements` package
+
+```
+npm install @warp-ds/elements
+```
+
+Add `@warp-ds/elements` to tsconfig types in compilerOptions.
+
+```json
+{
+  "compilerOptions": {
+    "types": ["react", "react-dom", "@warp-ds/elements"]
+  }
+}
+```
+
+#### Visual Studio Code
+
+This module includes [Custom HTML and CSS data for Visual Studio Code](https://code.visualstudio.com/blogs/2020/02/24/custom-data-format).
+
+##### Using Warp Elements in a plain HTML page
+
+When developing, install Warp Elements locally using npm
+
+```
+npm install @warp-ds/elements
+```
+
+Add the following snippet to settings.json in vscode to tell it about Warp components
+
+.vscode/settings.json
+
+```json
+{
+  "html.customData": [
+    "./node_modules/@warp-ds/elements/dist/vscode.html-custom-data.json"
+  ],
+  "css.customData": [
+    "./node_modules/@warp-ds/elements/dist/vscode.css-custom-data.json"
+  ]
+}
+```
+
+restart vscode
+
+Now, inside any .html files, you will get intellisense when using Warp Elements
 
 ```html
-<script src="https://assets.finn.no/pkg/@warp-ds/elements/v1"></script>
+<w-button variant=""><w-button>
+```
+
+##### Using Warp Elements in JavaScript template literals
+
+IntelliSense in JavaScript strings is not supported without additional plugins and syntax, such as comment hints (`/* html */`) or a tagged template literal similar to Lit.
+
+##### Using Warp Elements in Lit html tagged template literals
+
+When developing, install Warp Elements locally using npm
+
+```
+npm install @warp-ds/elements
 ```
-### Import components
-This project builds both the whole Elements package and separate component packages that are published to EIK, making it possible for the user to choose to either import all of the components:
+
+Add the following snippet to settings.json in vscode to tell it about Warp components
+
+.vscode/settings.json
+
+```json
+{
+  "html.customData": [
+    "./node_modules/@warp-ds/elements/dist/vscode.html-custom-data.json"
+  ],
+  "css.customData": [
+    "./node_modules/@warp-ds/elements/dist/vscode.css-custom-data.json"
+  ]
+}
+```
+
+Install the lit-plugin vscode extension and restart vscode
+
+Now, inside any html`` tagged template literals, you will get intellisense when using Warp Elements.
+
+```html
+<w-button variant=""><w-button>
+```
+
+##### Using Warp Elements in a React app, v19 or later
+
+```
+npm install @warp-ds/elements
+```
+
+Now, inside your react components, you will get intellisense when using Warp Elements.
+
+```html
+<w-button variant=""><w-button>
+```
+
+##### Using Warp Elements in a React app, v18 or earlier
+
+React 18 and earlier do not support custom elements.
+
+If you are on React 18 or early, we strongly urge you to please consider upgrading to React v19. 
+
+If you cannot upgrade right away, Warp supplies custom element wrappers to add backwards compatibility. Use them like so:
+
+```
+npm install @warp-ds/elements
+```
+
+Wherever you need to use a component in your app, import the appropriate element from the React namespace
+
 ```js
-import '@warp-ds/elements';
+import { Button } from "@warp-ds/elements/react/button";
 ```
-or a specific component: 
+
+and use the component
+
 ```js
-import '@warp-ds/elements/components/toast';
+<Button variant="primary"></Button>
 ```
 
-### Documentation
+you should get intellisense when using Warp Elements.
 
-For information on the components available in the package and how to use them,
-see the [Warp Design System documentation](https://warp-ds.github.io/tech-docs/).
+#### JetBrains products
 
-## Releases
+We ship `web-types.json` which should get picked up automatically by JetBrains IDEA and similar products.
 
-This project is continuously published to [NPM](https://www.npmjs.com/package/@warp-ds/elements) and [Eik](https://assets.finn.no/pkg/@warp-ds/elements) using a `next` tag (e.g. `1.1.0-next.1`).
-Anyone needing to use the latest changes of this package can point to the `next` version while waiting for the stable release.
+You should see code completions and inline docs for Warp elements when writing HTML.
 
-## Changelog
+### Ensure elements are ready (and avoid CLS and FOUCE)
 
-Detailed changes for each release can be found in the [CHANGELOG](CHANGELOG.md) file.
+To avoid issues like CLS (cumulative layout shift) and FOUCE (flash of unstyled custom elements), its important that Warp Elements is loaded before the page is rendered. For this reason, elements should not be bundled into the rest of your client side application and code and should be loaded in the document head, as early as possible (see installation above). When this is done correctly, elements will be loaded and ready about the same time as the rest of the page styles and wont cause delays in page load times. However, due to the way browsers work, a page render will occur without the components and an immediate re-render will occur with the components. This causes things to jump around on the page which in turn impacts lighthouse and other performance scores. Warp elements ships with a tool to prevent the initial render without components and only do the second, with components, render. This tool is called Warp Cloak and its usage is described below.
 
-## How to test component-classes locally
+#### The Warp cloaking device
 
-It is possible to test changes that have been made to component-classes from the [@warp-ds/css](https://github.com/warp-ds/css) package but that has not yet been published to Eik. You simply need to link the `@warp-ds/css` package in this repository and add `@unocss-placeholder` inside the static styles of the component that you want to test:
+To use the Warp cloaking device to avoid CLS and FOUCE, simply add the warp-cloak class to your pages body, html or a wrapper div that contains all the pages visible elements (including the header and footer)
 
-```js
-static styles = [
-    css`
-      @unocss-placeholder
-      `,
-  ]
+```html
+<body class="warp-cloak">
 ```
 
-Run `pnpm dev` to see the linked styles in action.
+That's it, your components should render just 1x, fully ready with no CLS and FOUCE.
 
-Once you have tested it locally, make sure to remove the `@unocss-placeholder` from the static styles before pushing any changes to the repository.
+## Releases
+
+This project is continuously published to [NPM](https://www.npmjs.com/package/@warp-ds/elements) and [Eik](https://assets.finn.no/pkg/@warp-ds/elements) using a `next` tag (e.g. `2.2.0-next.13`).
+Anyone needing to use the latest changes of this package can point to the `next` version while waiting for the stable release.
+
+## Changelog
+
+Detailed changes for each release can be found in the [CHANGELOG](CHANGELOG.md) file.
 
 ## License
 

package/dist/.storybook/utilities.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Massages storybook args before being spread to HTML attributes.
+ *
+ * - Empty strings are treated as not set.
+ * - Boolean false don't get set.
+ *
+ * @example
+ * ```ts
+ * import { html } from 'lit';
+ * import { spread } from '@open-wc/lit-helpers';
+ * import { prespread } from '../../.storybook/utilities.js';
+ *
+ * type Args = {
+ *   required: boolean;
+ * };
+ *
+ * const meta: Meta<Args> = {
+ *   component: 'w-component',
+ *   render(args) {
+ *     return html`<w-component ${spread(prespread(args))}></w-component>`;
+ *   },
+ *   argTypes: {
+ *     required: { type: 'boolean' },
+ *   },
+ * };
+ * ```
+ */
+export declare function prespread(args: Record<string, unknown>): Record<string, unknown>;

package/dist/.storybook/utilities.js

@@ -0,0 +1,52 @@
+/**
+ * Massages storybook args before being spread to HTML attributes.
+ *
+ * - Empty strings are treated as not set.
+ * - Boolean false don't get set.
+ *
+ * @example
+ * ```ts
+ * import { html } from 'lit';
+ * import { spread } from '@open-wc/lit-helpers';
+ * import { prespread } from '../../.storybook/utilities.js';
+ *
+ * type Args = {
+ *   required: boolean;
+ * };
+ *
+ * const meta: Meta<Args> = {
+ *   component: 'w-component',
+ *   render(args) {
+ *     return html`<w-component ${spread(prespread(args))}></w-component>`;
+ *   },
+ *   argTypes: {
+ *     required: { type: 'boolean' },
+ *   },
+ * };
+ * ```
+ */
+export function prespread(args) {
+    const newArgs = {
+        ...args,
+    };
+    for (const field of Object.keys(newArgs)) {
+        const value = args[field];
+        // Add Lit syntax for boolean attributes
+        if (typeof value === 'boolean') {
+            newArgs[`?${field}`] = value;
+            delete newArgs[field];
+        }
+        // Add Lit syntax for complex properties
+        if (typeof value === 'object') {
+            newArgs[`.${field}`] = value;
+            delete newArgs[field];
+        }
+        // The manifest has a bunch of default empty strings (which we should probably investigate)
+        // that turn on features that should be off in Storybook canvases.
+        // Remove the empty strings.
+        if (newArgs[field] === '') {
+            delete newArgs[field];
+        }
+    }
+    return newArgs;
+}

package/dist/api.js

@@ -1,50 +1,2 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
-
-// packages/utils/window-exists.js
-var windowExists = typeof window !== "undefined";
-
-// packages/toast/api.js
-function toast(message, options) {
-  if (!windowExists) return;
-  const toast2 = customElements.get("w-toast-container").init();
-  const data = __spreadValues({
-    id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),
-    text: message,
-    duration: 5e3,
-    type: "success"
-  }, options);
-  toast2.set(data);
-  return data;
-}
-function removeToast(id) {
-  if (!windowExists) return;
-  const toast2 = customElements.get("w-toast-container").init();
-  return toast2.del(id);
-}
-function updateToast(id, options) {
-  if (!windowExists) return;
-  const toast2 = customElements.get("w-toast-container").init();
-  toast2.set(__spreadValues(__spreadValues({}, toast2.get(id)), options));
-  return toast2.get(id);
-}
-export {
-  removeToast,
-  toast,
-  updateToast
-};
+var e=typeof window!="undefined";function r(){return customElements.get("w-toast-container")}function p(t,o){if(!e)return;let n=r().init(),s={id:Date.now().toString(36)+Math.random().toString(36).slice(2,5),text:t,duration:5e3,type:"success",...o};return n.set(s),s}function u(t){return e?r().init().del(t):void 0}function c(t,o){if(!e)return;let n=r().init();return n.set({...n.get(t),...o}),n.get(t)}export{u as removeToast,p as toast,c as updateToast};
 //# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../packages/utils/window-exists.js", "../packages/toast/api.js"],
-  "sourcesContent": ["export const windowExists = typeof window !== 'undefined';\n", "import { windowExists } from '../utils/window-exists';\n\n/**\n * Toast helper function options\n * @typedef    {Object}                         ToastOptions\n * @property   {(number|string)}                [id]        Custom identifier\n * @property   {('success'|'error'|'warning')}  [type]      Type of toast\n * @property   {String}                         [text]      The toast message. Only needed when updating text on existing toast\n * @property   {(number|string)}                [duration]  Duration of toast in milliseconds. Defaults to 5000. For accessibility reasons, toasts should never be interactive and therefore need to auto remove. If you must disable auto remove, set duration to Number.POSITIVE_INFINITY.\n * @property   {Boolean}                        [canclose]  Whether the toast can be dismissed. Defaults to false. WARNING! For accessibility reasons, toasts should not be interactive and canclose should always be false. If the toast absolutely must be dismissable, set this to true.\n */\n\n/**\n * Creates a new toast\n * @param {String}        message  Message\n * @param {ToastOptions?} options  Toast options\n * @returns {ToastOptions} Toast details\n */\nexport function toast(message, options) {\n  if (!windowExists) return;\n  const toast = customElements.get('w-toast-container').init();\n\n  const data = {\n    id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),\n    text: message,\n    duration: 5000,\n    type: 'success',\n    ...options,\n  };\n\n  toast.set(data);\n  return data;\n}\n\n/**\n * Remove an existing toast\n * @param {String|Number} id Toast identifier\n * @return {Promise<Boolean>} Resolves to true if deleted, false if not found\n */\nexport function removeToast(id) {\n  if (!windowExists) return;\n  const toast = customElements.get('w-toast-container').init();\n  return toast.del(id);\n}\n\n/**\n * Update an existing toast\n * @param {String|Number}           id      Toast identifier\n * @param {ToastOptions?}           options Toast options\n * @returns {WarpToastContainer}          Toast details\n */\nexport function updateToast(id, options) {\n  if (!windowExists) return;\n  const toast = customElements.get('w-toast-container').init();\n  toast.set({ ...toast.get(id), ...options });\n  return toast.get(id);\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAO,IAAM,eAAe,OAAO,WAAW;;;ACkBvC,SAAS,MAAM,SAAS,SAAS;AACtC,MAAI,CAAC,aAAc;AACnB,QAAMA,SAAQ,eAAe,IAAI,mBAAmB,EAAE,KAAK;AAE3D,QAAM,OAAO;AAAA,IACX,IAAI,KAAK,IAAI,EAAE,SAAS,EAAE,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC;AAAA,IACnE,MAAM;AAAA,IACN,UAAU;AAAA,IACV,MAAM;AAAA,KACH;AAGL,EAAAA,OAAM,IAAI,IAAI;AACd,SAAO;AACT;AAOO,SAAS,YAAY,IAAI;AAC9B,MAAI,CAAC,aAAc;AACnB,QAAMA,SAAQ,eAAe,IAAI,mBAAmB,EAAE,KAAK;AAC3D,SAAOA,OAAM,IAAI,EAAE;AACrB;AAQO,SAAS,YAAY,IAAI,SAAS;AACvC,MAAI,CAAC,aAAc;AACnB,QAAMA,SAAQ,eAAe,IAAI,mBAAmB,EAAE,KAAK;AAC3D,EAAAA,OAAM,IAAI,kCAAKA,OAAM,IAAI,EAAE,IAAM,QAAS;AAC1C,SAAOA,OAAM,IAAI,EAAE;AACrB;",
-  "names": ["toast"]
+  "sources": ["../packages/utils/window-exists.js", "../packages/toast/api.ts"],
+  "sourcesContent": ["export const windowExists = typeof window !== 'undefined';\n", "import { windowExists } from '../utils/window-exists';\n\nimport { WarpToastContainer } from './toast-container';\nimport type { ToastOptions, ToastInternal } from './types';\n\nfunction getToastContainer() {\n  const container = customElements.get('w-toast-container');\n  return container as typeof WarpToastContainer;\n}\n\n/**\n * Creates a new toast\n */\nexport function toast(message: string, options?: ToastOptions) {\n  if (!windowExists) return;\n\n  const toast = getToastContainer().init() as WarpToastContainer;\n\n  const data: ToastOptions = {\n    id: Date.now().toString(36) + Math.random().toString(36).slice(2, 5),\n    text: message,\n    duration: 5000,\n    type: 'success',\n    ...options,\n  };\n\n  toast.set(data);\n  return data;\n}\n\n/**\n * Remove an existing toast\n */\nexport function removeToast(id: string | number): Promise<boolean> | undefined {\n  if (!windowExists) return;\n\n  const toast = getToastContainer().init() as WarpToastContainer;\n  return toast.del(id);\n}\n\n/**\n * Update an existing toast\n */\nexport function updateToast(id: string | number, options?: ToastOptions): ToastInternal | undefined {\n  if (!windowExists) return;\n\n  const toast = getToastContainer().init() as WarpToastContainer;\n  toast.set({ ...toast.get(id), ...options });\n  return toast.get(id);\n}\n"],
+  "mappings": "AAAO,IAAMA,EAAe,OAAO,QAAW,YCK9C,SAASC,GAAoB,CAE3B,OADkB,eAAe,IAAI,mBAAmB,CAE1D,CAKO,SAASC,EAAMC,EAAiBC,EAAwB,CAC7D,GAAI,CAACC,EAAc,OAEnB,IAAMH,EAAQD,EAAkB,EAAE,KAAK,EAEjCK,EAAqB,CACzB,GAAI,KAAK,IAAI,EAAE,SAAS,EAAE,EAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAG,CAAC,EACnE,KAAMH,EACN,SAAU,IACV,KAAM,UACN,GAAGC,CACL,EAEA,OAAAF,EAAM,IAAII,CAAI,EACPA,CACT,CAKO,SAASC,EAAYC,EAAmD,CAC7E,OAAKH,EAESJ,EAAkB,EAAE,KAAK,EAC1B,IAAIO,CAAE,EAHA,MAIrB,CAKO,SAASC,EAAYD,EAAqBJ,EAAmD,CAClG,GAAI,CAACC,EAAc,OAEnB,IAAMH,EAAQD,EAAkB,EAAE,KAAK,EACvC,OAAAC,EAAM,IAAI,CAAE,GAAGA,EAAM,IAAIM,CAAE,EAAG,GAAGJ,CAAQ,CAAC,EACnCF,EAAM,IAAIM,CAAE,CACrB",
+  "names": ["windowExists", "getToastContainer", "toast", "message", "options", "windowExists", "data", "removeToast", "id", "updateToast"]
 }