@thepassle/app-tools 0.9.11 → 0.9.13

package/dialog/README.md

@@ -1,252 +0,0 @@
-# Pwa
-
-## Install
-
-```
-npm i -S @thepassle/app-tools
-```
-
-## Usage
-
-```js
-import { Dialog } from '@thepassle/app-tools/dialog.js'; 
-
-const dialog = new Dialog({
-  foo: { 
-    opening: (context) => {context.dialog.querySelector('form').innerHTML = 'hello world';},
-    opened: (context) => {},
-    closing: (context) => {},
-    closed: (context) => {}
-  },
-  bar: someAbstraction({
-    title: 'foo', 
-    import: () => import('./my-component.js'),
-    render: () => html`<my-dialog></my-dialog>`
-  }),
-});
-
-dialog.open({id: 'foo'});
-await dialog.opened;
-dialog.isOpen; // true
-/** Or */
-dialog.opened.then((context) => {});
-
-dialog.close();
-await dialog.closed;
-dialog.isOpen; // false
-/** Or */
-dialog.closed.then((context) => {});
-
-dialog.addEventListener('opening', ({context}) => {});
-dialog.addEventListener('opened', ({context}) => {});
-dialog.addEventListener('closing', ({context}) => {
-  console.log(dialog.returnValue);
-});
-dialog.addEventListener('closed', ({context}) => {
-  const { id, dialog } = context;
-  
-  if (id === 'foo') {
-    console.log(dialog.returnValue);
-  }
-
-  if(dialog.returnValue === 'dismiss') {
-    console.log('Dialog was closed via light dismiss');
-  }
-
-  if(dialog.returnValue === 'programmatic') {
-    console.log('Dialog was closed via `dialog.close()`');
-  }
-});
-
-dialog.modify((dialogNode) => {
-  dialogNode.classList.add('foo');
-});
-
-/** You can also pass parameters to the dialog renderer */
-dialog.open({
-  id: 'foo', 
-  parameters: {
-    foo: 'bar'
-  }
-});
-```
-
-## Callbacks
-
-```js
-import { Dialog } from '@thepassle/app-tools/dialog.js'; 
-
-const dialog = new Dialog({
-  foo: { 
-    /** 
-     * Executed right after the dialog has been created and added to the DOM, before animations have run
-     * Can be used for setup work, like adding `id`s to the dialog, lazy loading, 
-     * and rendering to the dialog's DOM
-     */
-    opening: (context) => {
-      context.dialog; // dialog node
-      context.id; // 'foo';
-      context.parameters; // { bar: 'bar' }
-    },
-    
-    /** 
-     * Executed after animations for the dialog element have run 
-     */
-    opened: (context) => {},
-    
-    /** 
-     * Executed when the native <dialog>'s `close` event has fired, on "light dismiss", 
-     * escape was pressed, or `dialog.close` was called
-     * Executed before animations 
-     * 
-     * Has access to `dialog.returnValue`
-     */
-    closing: (context) => {},
-
-    /** 
-     * Executed after the dialog's close animations have run and right before the dialog node is removed from the DOM 
-     * 
-     * Has access to `dialog.returnValue`
-     */
-    closed: (context) => {}
-  },
-});
-
-dialog.open({id: 'foo', parameters: {bar: 'bar'}})
-```
-
-## Styling the dialog
-
-It's recommended to provide a unique ID for the kind of dialog you want to show. For example:
-
-```js
-import { Dialog } from '@thepassle/app-tools/dialog.js'; 
-
-const dialog = new Dialog({
-  foo: { 
-    opening: ({dialog}) => {
-      dialog.id = 'foo';
-    },
-  },
-});
-```
-
-You can then, in your global stylesheet, select the dialog like so:
-```css
-dialog[app-tools]#foo {
-  border-radius: 10px;
-  background: lightgrey;
-  /* etc */
-}
-
-@media (max-width: 600px) {
-  dialog[app-tools]#foo {
-    width: 90%;
-  }
-}
-```
-
-## Animating the dialog
-
-```js
-import { Dialog } from '@thepassle/app-tools/dialog.js'; 
-
-const dialog = new Dialog({
-  foo: { 
-    opening: ({dialog}) => {
-      dialog.id = 'foo';
-      dialog.form.innerHTML = 'hello world';
-    },
-  },
-});
-
-dialog.open({id: 'foo'});
-```
-
-```css
-dialog[app-tools]#foo {
-  opacity: 0;
-  transform: translateY(40px);
-  transition: opacity .3s ease-out, transform .3s ease-out;
-}
-
-dialog[app-tools][open]#foo {
-  opacity: 1;
-  transform: translateY(0);
-}
-```
-
-## Abstractions
-
-It can be useful to declare some abstractions for the different kinds of dialogs you want to use in your app. Here's an example using Lit:
-
-```js
-import { html, render } from 'lit';
-import { Dialog } from '@thepassle/app-tools/dialog.js'; 
-
-function modal(config) {
-  return {
-    opening: ({dialog, parameters}) => {
-      config.import();
-      render(config.render({parameters, title: config.title}), dialog.form);
-    },
-    closing: ({dialog}) => {
-      console.log(dialog.returnValue); // "bar"
-    }
-  }
-}
-
-const dialog = new Dialog({
-  foo: modal({
-    title: 'Cart',
-    import: () => import('./shopping-cart.js'),
-    render: ({title, parameters}) => html`
-      <h1>${title}</h1>
-      <shopping-cart foo=${parameters.foo}></shopping-cart>
-      <button value="bar">Close</button>
-    `
-  })
-});
-
-dialog.open({id: 'foo', parameters: { foo: 'bar' }});
-```
-
-### Context menu
-
-```js
-import { computePosition } from '@floating-ui/dom';
-import { Dialog } from '@thepassle/app-tools';
-
-export const dialog = new Dialog({
-  context: context()
-});
-
-function context() {
-  return {
-    opening: async ({dialog, parameters, id}) => {
-      dialog.id = 'context';
-      render(parameters.template(), dialog.form);
-
-      if (!media.MAX.XS()) {
-        const { x, y } = await computePosition(
-          parameters.target, 
-          dialog, 
-          { placement: 'bottom-end'}
-        );
-        Object.assign(dialog.style, {
-          marginLeft: `${x}px`,
-          marginTop: `${y}px`,
-        });
-      }
-    }
-  }
-}
-
-dialog.open({
-  id: 'context', 
-  parameters: {
-    target: e.target,
-    template: () => html`<h1>hello world</h1>`
-  }
-});
-```

package/env/README.md

@@ -1,77 +0,0 @@
-# Env
-
-## Install
-
-```
-npm i -S @thepassle/app-tools
-```
-
-## Usage
-
-```js
-import { DEV, PROD } from '@thepassle/app-tools/env.js'; 
-
-if (DEV) {
-  console.log('Running in dev mode');
-}
-
-if (PROD) {
-  console.log('Running in prod mode');
-}
-```
-
-OR
-
-```js
-import { ENV } from '@thepassle/app-tools/env.js';
-
-if (ENV === 'dev') {
-  console.log('Running in dev mode');
-}
-
-if (ENV === 'prod') {
-  console.log('Running in prod mode');
-}
-```
-
-### Custom Env Modes
-
-In certain situations you might want to set your own env mode.
-
-Demos that should use "just" json files instead of a full api server might be a good use case for it.
-Here is an example using it in combination with the [Api Module](../api/README.md).
-
-```js
-import { ENV } from '@thepassle/app-tools/env.js';
-
-const baseURLs = {
-  'prod': 'https://api.domain.com', // prod api server
-  'dev': 'http://localhost:8888', // local api server
-  'dev-static': 'http://localhost:8000' // demos using "just" json files
-}
-const typedEnv = /** @type {keyof baseURLs} */ (ENV);
-
-export const api = new Api({
-  baseURL: baseURLs[typedEnv],
-});
-```
-
-Then in your HTML demo files you can set these special env values.
-
-```html
-<my-el api-endpoint="recommendation.json"></my-el>
-
-<script type="module">
-  import { ENV, setEnv } from '@thepassle/app-tools/env.js';
-  setEnv('dev-static');
-  import '../my-el.js';
-</script>
-```
-
-When resolving imports, Node will look for keys in the package export to figure out which file to use. For example "default", "import", or "require".
-
-Tools however can use custom keys here as well, like "types", "browser", "development", or "production". Depending on what kind of import it is, and which environment (dev/prod) tools (like bundlers or dev servers) can resolve/distinguish between which file should actually be used.
-
-## Acknowledgement
-
-This was inspired by [`esm-env`](https://github.com/benmccann/esm-env) by Ben McCann. I've added to my own repo because I like to have useful utils like these centralized in one place for my personal projects, especially when they're as small and elegant as this. 

package/pwa/README.md

@@ -1,103 +0,0 @@
-# Pwa
-
-## Install
-
-```
-npm i -S @thepassle/app-tools
-```
-
-## Usage
-
-Sets up global listeners for `'beforeinstallprompt'`, `'controllerchange'` as a side effect and correctly handles reloading when `'controllerchange'` has fired; it only reloads when a new service worker has activated, and there was a previous worker.
-
-```js
-import { PROD } from '@thepassle/app-tools/env.js';
-import { pwa } from '@thepassle/app-tools/pwa.js'; 
-
-pwa.updateAvailable; // false
-pwa.installable; // false
-pwa.installPrompt; // undefined
-/** Whether or not the PWA is running in standalone mode, and thus is installed as PWA */
-pwa.isInstalled; // false
-
-if (PROD) {
-  pwa.register('./sw.js', { scope: './' })
-    .catch(() => { 
-      console.log('Failed to register SW.') 
-    });
-}
-
-/** Fires an event when the PWA is considered installable by the browser */
-pwa.addEventListener('installable', () => {
-  pwa.installable; // true
-  pwa.installPrompt; // stores the beforeinstallprompt event
-  pwa.triggerPrompt(); // trigger the prompt
-});
-
-pwa.addEventListener('installed', ({installed}) => {
-  if (installed) {
-    /** The user accepted the install prompt, the PWA is successfully installed */
-  } else {
-    /** The user denied the prompt */
-  }
-});
-
-/** 
- * Fires when a service worker update is available 
- * Can be used to display a notification dot/icon to signal the user that an update is available,
- * or conditionally render some kind of "update" button
- */
-pwa.addEventListener('update-available', () => {
-  pwa.updateAvailable; // true
-  pwa.update(); // Sends a `{type: 'SKIP_WAITING'}` to the waiting service worker so it can take control of the page
-});
-
-/**
- * PWA kill switch. Unregisters service worker, deletes caches, reloads the browser
- */
-pwa.kill();
-```
-
-## Capabilities
-
-```js
-import { capabilities } from '@thepassle/app-tools/pwa.js';
-import { when } from '@thepassle/app-tools/utils.js';
-
-when(capabilities.WAKELOCK, () => html`<button>Request wakelock</button>`);
-
-// capabilities.BADGING
-// capabilities.NOTIFICATION
-// capabilities.SHARE
-// capabilities.SERVICEWORKER
-// capabilities.WAKELOCK
-```
-
-## Catching the `update` in your service worker file
-
-The `pwa.update()` method will `postMessage({type: 'SKIP_WAITING'})` to the currently `'waiting'` service worker. This is aligned with Workbox's defaults. However, if you are not using Workbox, make sure to add the following code to your service worker:
-
-```js
-self.addEventListener('message', (event) => {
-  if (event?.data?.type === 'SKIP_WAITING') {
-    self.skipWaiting();
-  }
-});
-```
-
-## Reloading when `'controllerchange'` fires
-
-The following code snippet usually does the rounds on the internet:
-
-```js
-let refreshing;
-navigator.serviceWorker.addEventListener('controllerchange', () => {
-  if (refreshing) return;
-  window.location.reload();
-  refreshing = true;
-});
-```
-
-However, this will also reload the page _the first time a user visits the page_ and leads to an unnecessary initial reload.
-
-`pwa` handles updates by making sure there was an old service worker to replace, to avoid the unnecessary initial reload.