@linzjs/windows 1.0.0

package/.eslintrc.cjs

@@ -0,0 +1,103 @@
+// This config will run in a way that fails a build
+module.exports = {
+  env: {
+    commonjs: true,
+    es2020: true,
+    node: true
+  },
+  plugins: ["react", "react-hooks", "jest", "jsx-a11y", "testing-library"],
+  settings: {
+    react: {
+      version: "detect"
+    },
+    jest: {
+      version: 26
+    }
+  },
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: "module"
+  },
+  extends: ["eslint:recommended", "plugin:react/recommended", "plugin:react-hooks/recommended", "plugin:jest/recommended", "plugin:jest/style", "plugin:testing-library/react", "plugin:prettier/recommended", "plugin:storybook/recommended"],
+  ignorePatterns: ["react-app-env.d.ts"],
+  rules: {
+    // testing-library - to fix
+    "testing-library/no-dom-import": "off",
+    // Fix these
+    "jest/no-conditional-expect": "off",
+    "jest/no-standalone-expect": "off",
+    "jest/valid-expect": "off",
+    "jest/prefer-to-be": "error",
+    "testing-library/no-unnecessary-act": "off",
+    "testing-library/prefer-presence-queries": "off",
+    "testing-library/no-wait-for-multiple-assertions": "off",
+    "testing-library/no-render-in-setup": "off",
+    "testing-library/no-node-access": "off",
+    "testing-library/prefer-screen-queries": "off",
+    "testing-library/prefer-find-by": "off",
+    "testing-library/prefer-query-by-disappearance": "off",
+    "testing-library/no-debugging-utils": "warn",
+    "testing-library/render-result-naming-convention": "off",
+    // customized rules
+    "react/no-unescaped-entities": ["error", {
+      forbid: [">", '"', "}"]
+    }],
+    // ' is ok, don't want to escape this
+    "react/react-in-jsx-scope": "off",
+    // TS config takes care of this
+    "linebreak-style": ["error", "unix"],
+    // prevent crlf from getting pushed
+    "react/prop-types": "off",
+    // Doesn't seem pick up React.FC<Props> typing
+    "no-console": ["error", {
+      allow: ["warn", "error"]
+    }],
+    // error on push/codacy
+    "jest/no-disabled-tests": "warn",
+    // we have some disabled tests
+    "no-unused-vars": "off",
+    // duplicate of typescript rule
+    "react/jsx-no-target-blank": "off",
+    "jest/expect-expect": "off",
+    // sometimes the assertions are in other functions called from a test
+
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": ["warn", {
+      additionalHooks: "(useWorkflowEffect|useWorkflowSidePanelHook)"
+    }]
+  },
+  overrides: [{
+    /** Overrides for typescript */
+    files: ["**/*.ts", "**/*.tsx"],
+    plugins: ["@typescript-eslint"],
+    parser: "@typescript-eslint/parser",
+    parserOptions: {
+      project: "./tsconfig.json",
+      tsconfigRootDir: __dirname
+    },
+    extends: ["plugin:@typescript-eslint/recommended"],
+    rules: {
+      "@typescript-eslint/await-thenable": "error",
+      "@typescript-eslint/no-unnecessary-type-constraint": "off",
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-empty-function": ["warn", {
+        allow: ["arrowFunctions"]
+      }],
+      "@typescript-eslint/no-unused-vars": ["error", {
+        argsIgnorePattern: "^_"
+      }],
+      // prepend var with _ (e.g.. _myVar) to ignore this pattern
+      "@typescript-eslint/no-use-before-define": "off",
+      // We will want to use before define to keep exports at the top
+      "@typescript-eslint/ban-ts-comment": "off",
+      // We use explicit overrides
+      "@typescript-eslint/naming-convention": "off" // React's convention is to use CamelCase for component file names
+    }
+  }, {
+    files: ["*.test.js", "*.test.ts", "*.test.tsx", "scripts/*"],
+    rules: {
+      "no-console": "off"
+    }
+  }]
+};

package/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# Basic dependabot.yml file with
+# minimum configuration for two package managers
+
+version: 2
+updates:
+  # Enable version updates for npm
+  - package-ecosystem: 'npm'
+    # Look for `package.json` and `lock` files in the `root` directory
+    directory: '/'
+    # Check the npm registry for updates every day (weekdays)
+    schedule:
+      interval: 'daily'

package/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+DESCRIPTION of the task, STORY/TASK number and link if applicable (e.g. SURVEY-100)
+
+Author Checklist
+
+- [ ] appropriate description or links provided to provide context on the PR
+- [ ] self reviewed, seems easy to understand and follow
+- [ ] reasonable code test coverage
+- [ ] change is documented in Storybook and/or markdown files
+
+Reviewer Checklist
+
+- Follows convention
+- Does what the author says it will do
+- Does not appear to cause side effects and breaking changes
+  - if it does cause breaking changes, those are appropriately referenced
+
+Post merge
+
+- [ ] Post about the change in #lui-cop
+
+Conventional Commit Cheat Sheet:
+**build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+**ci**: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs)
+**docs**: Documentation only changes
+**feat**: A new feature
+**fix**: A bug fix
+**perf**: A code change that improves performance
+**refactor**: A code change that neither fixes a bug nor adds a feature
+**test**: Adding missing tests or correcting existing tests

package/.github/workflows/chromatic.yml

@@ -0,0 +1,23 @@
+name: 'Chromatic'
+on: push
+
+jobs:
+  chromatic-deployment:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Install dependencies
+        run: npm i --legacy-peer-deps && npm run build-storybook
+      - name: Publish to non-master non-beta to Chromatic
+        if: github.ref != 'refs/heads/master' && github.ref != 'refs/heads/beta'
+        uses: chromaui/action@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+      - name: Publish Chromatic and auto accept changes for master and beta
+        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/beta'
+        uses: chromaui/action@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          autoAcceptChanges: true # 👈 Option to accept all changes

package/.github/workflows/deploy-storybook.yml

@@ -0,0 +1,86 @@
+name: CI
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Begin CI...
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+
+      - name: Use Node 16
+        uses: actions/setup-node@v2
+        with:
+          node-version: 16.x
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Test
+        run: npm run test --ci --coverage --maxWorkers=2
+
+      - name: Build
+        run: npm run build
+
+      - name: Release
+        if: github.ref == 'refs/heads/master'
+        run: npx semantic-release
+        env:
+          GH_TOKEN: ${{secrets.STEP_ENABLEMENT_SERVICE_PAT}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          NPM_TOKEN: ${{secrets.NPM_AUTH_TOKEN_LINZJS}}
+
+  publish-beta-npm:
+    if: startsWith(github.ref, 'refs/heads/beta')
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          token: ${{secrets.STEP_ENABLEMENT_SERVICE_PAT}}
+
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - run: npm version prerelease -m "%s [skip ci]" && git push
+        env:
+          GIT_AUTHOR_EMAIL: STEPEnablementService@linz.govt.nz
+          GIT_AUTHOR_NAME: STEP Enablement Service
+          GIT_COMMITTER_EMAIL: STEPEnablementService@linz.govt.nz
+          GIT_COMMITTER_NAME: STEP Enablement Service
+
+      - run: npm publish --access public --tag beta
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_AUTH_TOKEN_LINZJS}}
+
+  publish-storybook:
+    if: github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - run: npm run deploy-storybook -- --ci
+        env:
+          GH_TOKEN: github-actions:${{secrets.GITHUB_TOKEN}}

package/.prettierrc.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+  semi: true,
+  trailingComma: "all",
+  printWidth: 120,
+  useTabs: false,
+  tabWidth: 2,
+  singleQuote: false,
+  endOfLine: "lf",
+  importOrder: [".(css|scss)$", "<THIRD_PARTY_MODULES>", "^@linzjs/(.*)$", "^@step-ag-grid"],
+  importOrderSeparation: true,
+  importOrderSortSpecifiers: true,
+};

package/.storybook/main.ts

@@ -0,0 +1,17 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+const config: StorybookConfig = {
+  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
+  addons: [
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    "@storybook/addon-interactions",
+  ],
+  framework: {
+    name: "@storybook/react-vite",
+    options: {},
+  },
+  docs: {
+    autodocs: "tag",
+  },
+};
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,15 @@
+import type { Preview } from "@storybook/react";
+
+const preview: Preview = {
+  parameters: {
+    actions: { argTypesRegex: "^on[A-Z].*" },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+};
+
+export default preview;

package/.stylelintrc.json

@@ -0,0 +1,68 @@
+{
+  "extends": ["stylelint-config-standard", "stylelint-config-prettier", "stylelint-config-recommended-scss"],
+  "plugins": ["stylelint-scss"],
+  "customSyntax": "postcss-scss",
+  "rules": {
+    "at-rule-no-unknown": null,
+    "at-rule-empty-line-before": null,
+    "block-closing-brace-newline-before": "always-multi-line",
+    "block-closing-brace-newline-after": [
+      "always-multi-line",
+      {
+        "ignoreAtRules": ["if", "else"]
+      }
+    ],
+    "block-opening-brace-space-before": "always",
+    "block-opening-brace-space-after": "always-single-line",
+    "color-hex-case": null,
+    "color-hex-length": null,
+    "declaration-empty-line-before": null,
+    "declaration-block-single-line-max-declarations": 2,
+    "declaration-block-semicolon-newline-after": "always-multi-line",
+    "declaration-block-semicolon-space-after": "always-single-line",
+    "declaration-block-semicolon-space-before": "never",
+    "function-parentheses-space-inside": "never-single-line",
+    "function-max-empty-lines": 1,
+    "length-zero-no-unit": null,
+    "max-empty-lines": [
+      2,
+      {
+        "ignore": ["comments"]
+      }
+    ],
+    "no-duplicate-selectors": null,
+    "no-invalid-position-at-import-rule": null,
+    "rule-empty-line-before": [
+      "always-multi-line",
+      {
+        "except": ["after-single-line-comment", "first-nested"],
+        "ignore": ["after-comment", "first-nested"]
+      }
+    ],
+    "selector-list-comma-newline-after": "always-multi-line",
+    "selector-pseudo-element-colon-notation": "double",
+    "value-list-max-empty-lines": 1,
+
+    "scss/at-rule-no-unknown": true,
+    "scss/at-else-closing-brace-newline-after": "always-last-in-chain",
+    "scss/at-else-if-parentheses-space-before": "always",
+    "scss/no-duplicate-dollar-variables": [
+      true,
+      {
+        "ignoreInsideAtRules": ["if", "else", "mixin", "function", "while"]
+      }
+    ],
+    "scss/at-function-parentheses-space-before": "never",
+    "scss/at-if-closing-brace-newline-after": "always-last-in-chain",
+    "scss/at-mixin-argumentless-call-parentheses": "always",
+    "scss/at-mixin-parentheses-space-before": "never",
+    "scss/dollar-variable-colon-space-after": "at-least-one-space",
+    "scss/dollar-variable-colon-newline-after": "always-multi-line",
+    "scss/dollar-variable-no-missing-interpolation": true,
+    "scss/double-slash-comment-whitespace-inside": "always",
+    "scss/declaration-nested-properties-no-divided-groups": true,
+    "scss/operator-no-unspaced": true,
+    "scss/selector-no-redundant-nesting-selector": true,
+    "selector-class-pattern": "^[a-zA-Z-_]+$"
+  }
+}

package/README.md

@@ -0,0 +1,10 @@
+# linz/windows
+
+[![semantic-release](https://img.shields.io/badge/semantic--release-react-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+
+> Reusable windowing component for LINZ / Toitū te whenua.
+> 
+## Features
+    - Async React Modal dialogs
+
+See [Chromatic](https://64a2356b80885af35510b627-gsvwsgdsde.chromatic.com/) for usage.

package/config/jest/babelTransform.cjs

@@ -0,0 +1,29 @@
+"use strict";
+
+const babelJest = require("babel-jest");
+
+const hasJsxRuntime = (() => {
+  if (process.env.DISABLE_NEW_JSX_TRANSFORM === "true") {
+    return false;
+  }
+
+  try {
+    require.resolve("react/jsx-runtime");
+    return true;
+  } catch (e) {
+    return false;
+  }
+})();
+
+module.exports = babelJest.default.createTransformer({
+  presets: [
+    [
+      require.resolve("babel-preset-react-app"),
+      {
+        runtime: hasJsxRuntime ? "automatic" : "classic",
+      },
+    ],
+  ],
+  babelrc: false,
+  configFile: false,
+});

package/config/jest/cssTransform.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+// This is a custom Jest transformer turning style imports into empty objects.
+// http://facebook.github.io/jest/docs/en/webpack.html
+
+module.exports = {
+  process() {
+    return "module.exports = {};";
+  },
+  getCacheKey() {
+    // The output is always the same.
+    return "cssTransform";
+  },
+};

package/config/jest/fileTransform.cjs

@@ -0,0 +1,38 @@
+"use strict";
+
+const path = require("path");
+const lodash = require("lodash");
+
+// This is a custom Jest transformer turning file imports into filenames.
+// http://facebook.github.io/jest/docs/en/webpack.html
+
+module.exports = {
+  process(src, filename) {
+    const assetFilename = JSON.stringify(path.basename(filename));
+
+    if (filename.match(/\.svg$/)) {
+      // Based on how SVGR generates a component name:
+      // https://github.com/smooth-code/svgr/blob/01b194cf967347d43d4cbe6b434404731b87cf27/packages/core/src/state.js#L6
+      const pascalCaseFilename = lodash.upperFirst(lodash.camelCase(path.parse(filename).name));
+      const componentName = `Svg${pascalCaseFilename}`;
+      return `const React = require('react');
+      module.exports = {
+        __esModule: true,
+        default: ${assetFilename},
+        ReactComponent: React.forwardRef(function ${componentName}(props, ref) {
+          return {
+            $$typeof: Symbol.for('react.element'),
+            type: 'svg',
+            ref: ref,
+            key: null,
+            props: Object.assign({}, props, {
+              children: ${assetFilename}
+            })
+          };
+        }),
+      };`;
+    }
+
+    return `module.exports = ${assetFilename};`;
+  },
+};

package/config/jest/setup.js

@@ -0,0 +1,2 @@
+import "@testing-library/jest-dom";
+import "jest-canvas-mock";

package/empty.js

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

package/jest.config.cjs

@@ -0,0 +1,19 @@
+module.exports = {
+  roots: ["<rootDir>/src"],
+  collectCoverageFrom: ["src/**/*.{js,jsx,ts,tsx}", "!src/**/*.d.ts"],
+  setupFiles: ["react-app-polyfill/jsdom"],
+  setupFilesAfterEnv: ["jest-expect-message"],
+  testMatch: ["<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}"],
+  testEnvironment: "jsdom",
+  transform: {
+    "^.+\\.(js|jsx|mjs|cjs|ts|tsx)$": "<rootDir>/config/jest/babelTransform.cjs",
+    "^.+\\.css$": "<rootDir>/config/jest/cssTransform.cjs",
+    "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)": "<rootDir>/config/jest/fileTransform.cjs",
+  },
+  transformIgnorePatterns: ["node_modules/(?!(ol|@geoblocks/ol-maplibre-layer|geotiff|quick-lru)|lodash-es|lodash|escape-string-regexp|matcher/)"],
+  moduleNameMapper: {
+    "^@components/(.*)$": "<rootDir>/src/components/$1",
+  },
+  resetMocks: true,
+  coverageReporters: ["text", "cobertura"],
+};

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@linzjs/windows",
+  "repository": "github:linz/windows.git",
+  "license": "MIT",
+  "version": "1.0.0",
+  "peerDependencies": {
+    "lodash-es": ">=4",
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "lodash-es": ">=4",
+    "react": ">=17",
+    "react-dom": ">=17",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.2",
+    "@rollup/plugin-json": "^6.0.0",
+    "@rollup/plugin-node-resolve": "^15.1.0",
+    "@storybook/addon-docs": "^7.0.24",
+    "@storybook/addon-essentials": "^7.0.24",
+    "@storybook/addon-interactions": "^7.0.24",
+    "@storybook/addon-links": "^7.0.24",
+    "@storybook/blocks": "^7.0.24",
+    "@storybook/builder-webpack5": "^7.0.24",
+    "@storybook/jest": "^0.1.0",
+    "@storybook/preset-create-react-app": "^7.0.24",
+    "@storybook/react": "^7.0.24",
+    "@storybook/react-vite": "^7.0.24",
+    "@storybook/test-runner": "^0.11.0",
+    "@storybook/testing-library": "^0.2.0",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.4.3",
+    "@trivago/prettier-plugin-sort-imports": "^4.1.1",
+    "@types/jest": "^29.5.2",
+    "@types/lodash-es": "^4.17.7",
+    "@types/node": "^20.3.3",
+    "@types/react": "^18.2.14",
+    "@types/react-dom": "^18.2.6",
+    "@types/uuid": "^9.0.2",
+    "eslint": "^8.44.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-config-react-app": "^7.0.1",
+    "eslint-plugin-deprecation": "^1.4.1",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-jest": "^27.2.2",
+    "eslint-plugin-jsx-a11y": "^6.7.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-storybook": "^0.6.12",
+    "eslint-plugin-testing-library": "^5.11.0",
+    "jest": "^29.5.0",
+    "jest-canvas-mock": "^2.5.2",
+    "jest-environment-jsdom": "^29.5.0",
+    "jest-expect-message": "^1.1.3",
+    "mkdirp": "^3.0.1",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^2.8.8",
+    "prop-types": "^15.8.1",
+    "react-scripts": "5.0.1",
+    "rollup": "^3.23.0",
+    "rollup-plugin-copy": "^3.4.0",
+    "sass": "^1.63.6",
+    "sass-loader": "^13.3.2",
+    "semantic-release": "^19.0.5",
+    "storybook": "^7.0.24",
+    "style-loader": "^3.3.3",
+    "stylelint": "^14.16.1",
+    "stylelint-config-prettier": "^9.0.5",
+    "stylelint-config-recommended-scss": "^8.0.0",
+    "stylelint-config-standard": "^29.0.0",
+    "stylelint-prettier": "3.0.0",
+    "stylelint-scss": "5.0.1",
+    "typescript": "^4.9.5",
+    "vite": "^4.3.9"
+  },
+  "scripts": {
+    "build": "run-s clean stylelint lint bundle",
+    "yalc": "run-s clean css bundle && yalc publish",
+    "clean": "rimraf dist && mkdirp ./dist",
+    "bundle": "rollup -c",
+    "test": "jest",
+    "stylelint": "stylelint src/**/*.scss src/**/*.css --fix",
+    "lint": "eslint ./src --ext .js,.ts,.tsx --fix --cache --ignore-path .gitignore",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "deploy-storybook": "npx --yes -p @storybook/storybook-deployer storybook-to-ghpages",
+    "chromatic": "chromatic --exit-zero-on-changes",
+    "semantic-release": "semantic-release"
+  },
+  "eslintConfig": {
+    "extends": [
+      "react-app",
+      "react-app/jest"
+    ]
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run lint"
+    }
+  }
+}

package/rollup.config.cjs

@@ -0,0 +1,26 @@
+const copy  = require("rollup-plugin-copy");
+
+const outputDir = "dist";
+
+module.exports = {
+  input: "./empty.js",
+  plugins: [
+    copy({
+      targets: [
+        {
+          src: ["src/modal/*", "!**/*.test.ts*"],
+          dest: outputDir,
+          expandDirectories: true,
+          onlyFiles: true,
+        },
+        {
+          src: ["src/util/*", "!**/*.test.ts*"],
+          dest: outputDir,
+          expandDirectories: true,
+          onlyFiles: true,
+        },
+      ],
+      flatten: false,
+    }),
+  ],
+};

package/src/modal/Modal.tsx

@@ -0,0 +1,32 @@
+import { ModalInstanceContext } from "./ModalInstanceContext";
+import { defer } from "lodash-es";
+import { ReactElement, useContext, useEffect, useRef } from "react";
+
+export interface ModalProps {
+  selectFirstInput?: boolean;
+  children: ReactElement | ReactElement[];
+}
+
+export const Modal = ({ selectFirstInput = true, children }: ModalProps): ReactElement => {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  const { close } = useContext(ModalInstanceContext);
+
+  // The only way to create a modal dialog is to call showModal, open attribute will not work
+  useEffect(() => {
+    // Check if it's open already to support .vite hot deploys
+    if (!dialogRef.current?.open) {
+      dialogRef.current?.showModal();
+    }
+  }, []);
+
+  useEffect(() => {
+    selectFirstInput && defer(() => dialogRef.current?.querySelector("input")?.select());
+  }, [selectFirstInput]);
+
+  return (
+    <dialog ref={dialogRef} onClick={(e) => e.target === e.currentTarget && close()} style={{ padding: 0 }}>
+      {children}
+    </dialog>
+  );
+};

package/src/modal/ModalContext.tsx

@@ -0,0 +1,27 @@
+import { ComponentProps, MutableRefObject, ReactElement, createContext } from "react";
+
+export type ComponentType = (props: any) => ReactElement<any, any>;
+
+export interface ModalCallback<R> {
+  resolve: (result: R | undefined) => void;
+  close: () => void;
+}
+
+export interface ModalContextType {
+  showModal: <
+    OR extends HTMLElement | null,
+    PROPS extends ModalCallback<any>,
+    CT extends (props: PROPS) => ReactElement<any, any>,
+    RT = Parameters<Parameters<CT>[0]["resolve"]>[0],
+  >(
+    ownerRef: MutableRefObject<OR>,
+    component: CT,
+    args: Omit<ComponentProps<CT>, "resolve" | "close">,
+  ) => Promise<RT>;
+}
+
+export const ModalContext = createContext<ModalContextType>({
+  showModal: (async () => {
+    console.error("Missing ModalContext Provider");
+  }) as ModalContextType["showModal"],
+});

package/src/modal/ModalContextProvider.tsx

@@ -0,0 +1,137 @@
+import { useInterval } from "../util/useInterval";
+import { ComponentType, ModalContext } from "./ModalContext";
+import { ModalInstanceContext } from "./ModalInstanceContext";
+import { Fragment, MutableRefObject, ReactElement, useState } from "react";
+import * as ReactDOM from "react-dom";
+import { v4 as uuid } from "uuid";
+
+export interface ModalInstance {
+  uuid: string;
+  ownerElement: Element | undefined;
+  componentInstance: ReactElement;
+  resolve: (result: any) => void;
+}
+
+/**
+ * Provides the ability to show modals using react components without needing useState boilerplate and inline dialogs.
+ *
+ * To use:
+ * <ol>
+ * <li>Add this Provider somewhere in your standard providers
+ * <pre>
+ * <ModalContextProvider>
+ *    ...children
+ * </ModalContextProvider>
+ * </pre>
+ * </li>
+ * <li>Add the modal return type to the element as below, and use the props resolve/close from ModalProps for results.
+ * <pre>
+ * export interface SomeModalProps extends ModalProps<number> {
+ *   someProp?: number; // user props
+ * }
+ *
+ * export const SomeModal = ({initialState, resolve, close}: SomeModalProps): ReactElement => {
+ *    return Modal(
+ *       <div>
+ *           Itsa me, I'm modal
+ *          <button onClick={close}>Cancel</button>
+ *          <button onClick={()=>resolve(someProp)}>Save</button>
+ *       </div>
+ *    )}
+ * }
+ * </pre>
+ * </li>
+ * <li> To show the dialog and get the result...
+ * <pre>
+ *   // Note: modalOwnerRef is only required if you need to support popout windows
+ *   const { showModal, modalOwnerRef  } = useContext(ModalContext);
+ *   ...
+ *   const showModal = () => {
+ *     const result = await showModal(SomeModal, { someProp: 1 });
+ *     if (!result) return; // modal cancelled
+ *   }
+ *
+ *   return <button onClick={showModal} ref={modalOwnerRef}>Show Modal!</button>
+ * </pre>
+ * </li>
+ * </ol>
+ */
+export const ModalContextProvider = ({ children }: { children: ReactElement }): ReactElement => {
+  const [modals, setModals] = useState<ModalInstance[]>([]);
+
+  /**
+   * Inserts the modal into the page, and removes once modal has a result.
+   * Note: full generic types are provided by the interface.  Function def has been simplified here.
+   *
+   * @param ownerRef Reference to div that opened this dialog such that it works for popout windows.
+   * @param Component React component.
+   * @param args Arguments for react component.
+   */
+  const showModal = async (
+    ownerRef: MutableRefObject<HTMLElement | null>,
+    Component: ComponentType,
+    args: any,
+  ): Promise<any> => {
+    let componentInstance: ReactElement | undefined;
+    const promise = new Promise((resolve) => {
+      try {
+        // If there are any exceptions the modal won't show
+        setModals([
+          ...modals,
+          {
+            uuid: uuid(),
+            ownerElement: ownerRef.current ?? document.body,
+            componentInstance: <Component {...args} resolve={resolve} close={() => resolve(undefined)} />,
+            resolve,
+          },
+        ]);
+      } catch (e) {
+        console.error(e);
+        return;
+      }
+    });
+
+    // Wait for modal to complete
+    const result = await promise;
+
+    // Close modal
+    setModals(modals.filter((e) => e.componentInstance !== componentInstance));
+
+    return result;
+  };
+
+  const modalHasView = (modalInstance: ModalInstance): boolean =>
+    !!modalInstance.ownerElement?.ownerDocument?.defaultView;
+
+  // Tidy up modals that have closed because of an external window closing
+  useInterval(() => {
+    const newModals = modals.filter(modalHasView);
+    if (newModals.length !== modals.length) {
+      setModals(newModals);
+    }
+  }, 1000);
+
+  return (
+    <ModalContext.Provider
+      value={{
+        showModal,
+      }}
+    >
+      <>
+        <Fragment key={"modals"}>
+          {modals
+            .filter(modalHasView)
+            .map((modalInstance) =>
+              ReactDOM.createPortal(
+                <ModalInstanceContext.Provider value={{ close: () => modalInstance.resolve(undefined) }}>
+                  {modalInstance.componentInstance}
+                </ModalInstanceContext.Provider>,
+                (modalInstance.ownerElement?.ownerDocument ?? document).body,
+              ),
+            )}
+        </Fragment>
+        <Fragment key={"children"}>{children}</Fragment>
+      </>
+    </ModalContext.Provider>
+  );
+};

package/src/modal/ModalInstanceContext.ts

@@ -0,0 +1,16 @@
+import { createContext } from "react";
+
+export interface ModalInstanceContextType {
+  close: () => void;
+}
+
+const NoContextError = () => {
+  console.error("Missing ModalInstanceContext Provider");
+};
+
+/**
+ * Provides access to resolving/closing to modal elements.
+ */
+export const ModalInstanceContext = createContext<ModalInstanceContextType>({
+  close: NoContextError,
+});

package/src/modal/useShowModal.ts

@@ -0,0 +1,16 @@
+import { ComponentType, ModalContext } from "./ModalContext";
+import { ComponentProps, useContext, useRef } from "react";
+
+export const useShowModal = () => {
+  const { showModal } = useContext(ModalContext);
+
+  const modalOwnerRef = useRef<any>(null);
+
+  return {
+    showModal: <CT extends ComponentType>(
+      component: CT,
+      args: Omit<ComponentProps<CT>, "resolve" | "close">,
+    ): Promise<Parameters<Parameters<CT>[0]["resolve"]>[0]> => showModal(modalOwnerRef, component, args),
+    modalOwnerRef,
+  };
+};

package/src/setupTests.ts

@@ -0,0 +1,5 @@
+// jest-dom adds custom jest matchers for asserting on DOM nodes.
+// allows you to do things like:
+// expect(element).toHaveTextContent(/react/i)
+// learn more: https://github.com/testing-library/jest-dom
+import "@testing-library/jest-dom";

package/src/stories/modal/Modal.mdx

@@ -0,0 +1,20 @@
+import {Meta, Source, Story} from "@storybook/blocks";
+import * as ModalStories from "./Modal.stories"
+
+import myModule from './TestModal?raw';
+
+<Meta title="Modal/Primary" of={ModalStories}/>
+# Show Modal
+## Example
+Click to show the modal:
+<Story of={ModalStories.ShowModal}/>
+
+## Code
+<br/>
+{myModule.toString().split("// #").splice(1).map(block => (
+<>
+    <h3>{block.split("\n")[0]}</h3>
+    <Source code={block.split("\n").splice(1).join("\n")} language='typescript'/>
+</>
+))}
+

package/src/stories/modal/Modal.stories.tsx

@@ -0,0 +1,27 @@
+import { ModalContextProvider } from "../../modal/ModalContextProvider";
+import { TestModalUsage } from "./TestModal";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: Meta<typeof TestModalUsage> = {
+  title: "Modal",
+  component: TestModalUsage,
+  argTypes: {
+    backgroundColor: { control: "color" },
+  },
+  decorators: [
+    (Story: any) => (
+      <div>
+        <ModalContextProvider>
+          <Story />
+        </ModalContextProvider>
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ShowModal: Story = {
+  args: {},
+};

package/src/stories/modal/TestModal.scss

@@ -0,0 +1,15 @@
+dialog > div {
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+
+  div {
+    display: flex;
+    gap: 10px;
+  }
+
+  button {
+    flex: 1;
+  }
+}

package/src/stories/modal/TestModal.tsx

@@ -0,0 +1,57 @@
+import "./TestModal.scss";
+
+import { Modal } from "../../modal/Modal";
+import { ModalCallback } from "../../modal/ModalContext";
+import { ModalContextProvider } from "../../modal/ModalContextProvider";
+import { useShowModal } from "../../modal/useShowModal";
+
+// #Example: Modal Context Provider
+// Don't forget to add a ModalContextProvider at the root of your project
+export const App = () => (
+  <ModalContextProvider>
+    <div>...the rest of your app...</div>
+  </ModalContextProvider>
+);
+
+// #Example: Modal Component
+// Extend your props with ModalCallback<RESULT_TYPE> to add a return type, and enable close/resolve
+export interface TestModalProps extends ModalCallback<number> {
+  text: string; // A user property
+}
+
+// Close and resolve will be passed to your props magically!
+export const TestModal = ({ text, close, resolve }: TestModalProps) => (
+  <Modal>
+    <div>
+      <div>This is the modal text: '{text}'</div>
+      <div>
+        <button onClick={close}>Close</button>
+        <button onClick={() => resolve(1)}>Return 1</button>
+      </div>
+    </div>
+  </Modal>
+);
+
+// #Example: Modal Invocation
+export const TestModalUsage = () => {
+  // showModal to show modal, modalOwnerRef is only required if you have popout windows
+  const { showModal, modalOwnerRef } = useShowModal();
+
+  const showModalHandler = async () => {
+    // Show modal and await result
+    const result = await showModal(TestModal, { text: "Text text" });
+
+    // If result is undefined the modal was closed
+    if (!result) return alert("Modal closed");
+
+    // Otherwise we have a result
+    alert(`Modal result is: ${result}`);
+  };
+
+  // Remember to add the modalOwnerRef!
+  return (
+    <div ref={modalOwnerRef}>
+      <button onClick={showModalHandler}>Show modal</button>
+    </div>
+  );
+};

package/src/util/useInterval.test.tsx

@@ -0,0 +1,26 @@
+import { useInterval } from "./useInterval";
+import { render } from "@testing-library/react";
+
+describe("useInterval", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(async () => {
+    jest.useRealTimers();
+  });
+
+  const TestComponent = (props: { callback: () => void }) => {
+    useInterval(props.callback, 1000);
+    return <div />;
+  };
+
+  test("invokes on timeout", async () => {
+    const callback = jest.fn();
+
+    render(<TestComponent callback={callback} />);
+    expect(callback).toHaveBeenCalledTimes(0);
+    jest.runOnlyPendingTimers();
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+});

package/src/util/useInterval.ts

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from "react";
+
+type Callback = () => void | Promise<void>;
+
+export const useInterval = (callback: Callback, delay: number | null) => {
+  const savedCallback = useRef(callback);
+  const callbackInProgress = useRef(false);
+  savedCallback.current = callback;
+
+  useEffect(() => {
+    if (delay == null) return;
+
+    const id = setInterval(async () => {
+      // Since this is an interval, then next tick could occur before the previous has finished
+      if (!callbackInProgress.current && savedCallback.current) {
+        callbackInProgress.current = true;
+        try {
+          await savedCallback.current();
+        } finally {
+          callbackInProgress.current = false;
+        }
+      }
+    }, delay);
+    return () => clearInterval(id);
+  }, [delay]);
+};

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  // see https://www.typescriptlang.org/tsconfig to better understand tsconfigs
+  "include": ["src"],
+  "files": ["node_modules/jest-expect-message/types/index.d.ts"],
+  "compilerOptions": {
+    "baseUrl": "./src",
+    "module": "esnext",
+    "lib": ["dom", "esnext"],
+    "target": "ESNext",
+    "importHelpers": true,
+    // output .d.ts declaration files for consumers
+    "declaration": true,
+    // output .js.map sourcemap files for consumers
+    "sourceMap": true,
+    // match output dir to input dir. e.g. dist/index instead of dist/src/index
+    "rootDir": ".",
+    // stricter type-checking for stronger correctness. Recommended by TS
+    "strict": true,
+    // linter checks for common issues
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    // noUnused* overlap with @typescript-eslint/no-unused-vars, can disable if duplicative
+    "noUnusedLocals": false,
+    "noUnusedParameters": true,
+    // use Node's module resolution algorithm, instead of the legacy TS one
+    "moduleResolution": "node",
+    // transpile JSX to React.createElement
+    "jsx": "react-jsx",
+    // interop between ESM and CJS modules. Recommended by TS
+    "esModuleInterop": true,
+    // significant perf increase by skipping checking .d.ts files, particularly those in node_modules. Recommended by TS
+    "skipLibCheck": true,
+    // error out if import and file system have a casing mismatch. Recommended by TS
+    "forceConsistentCasingInFileNames": true,
+    "declarationDir":"./declaration"
+  }
+}