@availity/mui-authorize 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## 0.1.0 (2024-05-10)
+
+### Dependency Updates
+
+* `mui-block-ui` updated to version `0.1.0`
+
+### Features
+
+* **mui-authorize:** add authorize package ([ff64501](https://github.com/Availity/element/commit/ff6450141021d74657e53e85213ce00b638a6465))

package/README.md

@@ -0,0 +1,61 @@
+# @availity/mui-authorize
+
+> Availity MUI Authorize component to be used with @availity/element design system.
+
+[![Version](https://img.shields.io/npm/v/@availity/mui-authorize.svg?style=for-the-badge)](https://www.npmjs.com/package/@availity/mui-authorize)
+[![NPM Downloads](https://img.shields.io/npm/dt/@availity/mui-authorize.svg?style=for-the-badge)](https://www.npmjs.com/package/@availity/mui-authorize)
+[![Dependency Status](https://img.shields.io/librariesio/release/npm/@availity/mui-authorize?style=for-the-badge)](https://github.com/Availity/element/blob/main/packages/mui-authorize/package.json)
+
+## Documentation
+
+This package extends the MUI Authorize component: [MUI Authorize Docs](https://mui.com/components/authorize/)
+
+Live demo and documentation in our [Storybook](https://availity.github.io/element/?path=/docs/components-authorize-introduction--docs)
+
+Availity standards for design and usage can be found in the [Availity Design Guide](https://zeroheight.com/2e36e50c7)
+
+## Installation
+
+### Import Through @availity/element (Recommended)
+
+#### NPM
+
+```bash
+npm install @availity/element
+```
+
+#### Yarn
+
+```bash
+yarn add @availity/element
+```
+
+### Direct Import
+
+#### NPM
+
+_This package has a few peer dependencies. Add `@mui/material` & `@emotion/react` to your project if not already installed._
+
+```bash
+npm install @availity/mui-authorize
+```
+
+#### Yarn
+
+```bash
+yarn add @availity/mui-authorize
+```
+
+### Usage
+
+#### Import through @availity/element
+
+```tsx
+import { Authorize } from '@availity/element';
+```
+
+#### Direct import
+
+```tsx
+import { Authorize } from '@availity/mui-authorize';
+```

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { UseAuthorizeProps } from '@availity/authorize';
+
+type AuthorizeProps = {
+    /** The content that renders when the user does have the permissions required. */
+    children?: ReactNode;
+    /** When true, BlockUi is used when loading the permissions. When a node, that node is rendered instead of BlockUi when loading the permissions. When false, nothing is rendered when loading the permissions. Default: true. */
+    loader?: boolean | ReactNode;
+    /** Negate the authorization. If the user does have the permissions specified, they are considered "unauthorized" (shown the unauthorized prop content). If the user does not have the permissions specified, they are considered "authorized" (shown the children prop content) */
+    negate?: boolean;
+    /** The content that renders when the user does not have the permissions required. */
+    unauthorized?: ReactNode;
+} & UseAuthorizeProps;
+/** Component for showing content based on the user's permissions. Wrap this component around content you only want specific users to see.
+ *
+ * The `useAuthorize` hook utilizes [react-query](https://tanstack.com/query/v4/docs/framework/react/overview) to handle data fetching.
+ * This means you must add a [QueryClientProvider](https://tanstack.com/query/v4/docs/framework/react/reference/QueryClientProvider)
+ * to your app if you do not already have one.
+ *
+ * The default setup should cover most use-cases. However, there are 2 query options we recommend looking into
+ * in order to determine what is correct for your app. These settings are `refetchOnWindowFocus` and
+ * `staleTime`. The first option sets whether the to refetch the query when the window is focused, and
+ * the other is the default marker for how long the query is valid.
+ */
+declare const Authorize: ({ loader, negate, children, unauthorized, permissions, parameters, queryOptions }: AuthorizeProps) => JSX.Element | null;
+
+export { Authorize, type AuthorizeProps };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { UseAuthorizeProps } from '@availity/authorize';
+
+type AuthorizeProps = {
+    /** The content that renders when the user does have the permissions required. */
+    children?: ReactNode;
+    /** When true, BlockUi is used when loading the permissions. When a node, that node is rendered instead of BlockUi when loading the permissions. When false, nothing is rendered when loading the permissions. Default: true. */
+    loader?: boolean | ReactNode;
+    /** Negate the authorization. If the user does have the permissions specified, they are considered "unauthorized" (shown the unauthorized prop content). If the user does not have the permissions specified, they are considered "authorized" (shown the children prop content) */
+    negate?: boolean;
+    /** The content that renders when the user does not have the permissions required. */
+    unauthorized?: ReactNode;
+} & UseAuthorizeProps;
+/** Component for showing content based on the user's permissions. Wrap this component around content you only want specific users to see.
+ *
+ * The `useAuthorize` hook utilizes [react-query](https://tanstack.com/query/v4/docs/framework/react/overview) to handle data fetching.
+ * This means you must add a [QueryClientProvider](https://tanstack.com/query/v4/docs/framework/react/reference/QueryClientProvider)
+ * to your app if you do not already have one.
+ *
+ * The default setup should cover most use-cases. However, there are 2 query options we recommend looking into
+ * in order to determine what is correct for your app. These settings are `refetchOnWindowFocus` and
+ * `staleTime`. The first option sets whether the to refetch the query when the window is focused, and
+ * the other is the default marker for how long the query is valid.
+ */
+declare const Authorize: ({ loader, negate, children, unauthorized, permissions, parameters, queryOptions }: AuthorizeProps) => JSX.Element | null;
+
+export { Authorize, type AuthorizeProps };

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Authorize: () => Authorize
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lib/Authorize.tsx
+var import_mui_block_ui = require("@availity/mui-block-ui");
+var import_authorize = require("@availity/authorize");
+var import_jsx_runtime = require("react/jsx-runtime");
+var Authorize = ({
+  loader = true,
+  negate = false,
+  children = null,
+  unauthorized = null,
+  permissions,
+  parameters = {},
+  queryOptions
+}) => {
+  const { authorized, isLoading } = (0, import_authorize.useAuthorize)(permissions, parameters, queryOptions);
+  if (isLoading) {
+    if (loader)
+      return loader === true ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_mui_block_ui.BlockUi, { blocking: true }) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: loader });
+    return null;
+  }
+  if ((authorized || negate) && !(authorized && negate)) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: unauthorized });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Authorize
+});

package/dist/index.mjs

@@ -0,0 +1,27 @@
+// src/lib/Authorize.tsx
+import { BlockUi } from "@availity/mui-block-ui";
+import { useAuthorize } from "@availity/authorize";
+import { Fragment, jsx } from "react/jsx-runtime";
+var Authorize = ({
+  loader = true,
+  negate = false,
+  children = null,
+  unauthorized = null,
+  permissions,
+  parameters = {},
+  queryOptions
+}) => {
+  const { authorized, isLoading } = useAuthorize(permissions, parameters, queryOptions);
+  if (isLoading) {
+    if (loader)
+      return loader === true ? /* @__PURE__ */ jsx(BlockUi, { blocking: true }) : /* @__PURE__ */ jsx(Fragment, { children: loader });
+    return null;
+  }
+  if ((authorized || negate) && !(authorized && negate)) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children: unauthorized });
+};
+export {
+  Authorize
+};

package/introduction.stories.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '@storybook/blocks';
+import { Meta } from '@storybook/addon-docs';
+import ReadMe from './README.md?raw';
+
+<Meta title="Components/Authorize/Introduction" />
+
+<Markdown>{ReadMe}</Markdown>

package/jest.config.js

@@ -0,0 +1,7 @@
+const global = require('../../jest.config.global');
+
+module.exports = {
+  ...global,
+  displayName: 'authorize',
+  coverageDirectory: '../../coverage/authorize'
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@availity/mui-authorize",
+  "version": "0.1.0",
+  "description": "Availity Authorize Component - part of the @availity/element design system",
+  "keywords": [
+    "react",
+    "typescript",
+    "availity",
+    "mui"
+  ],
+  "homepage": "https://availity.github.io/element/?path=/docs/components-authorize-introduction--docs",
+  "bugs": {
+    "url": "https://github.com/Availity/element/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Availity/element.git",
+    "directory": "packages/authorize"
+  },
+  "license": "MIT",
+  "author": "Availity Developers <AVOSS@availity.com>",
+  "browser": "./dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --watch --dts",
+    "clean": "rm -rf dist",
+    "clean:nm": "rm -rf node_modules",
+    "publish": "yarn npm publish --tolerate-republish --access public",
+    "publish:canary": "yarn npm publish --access public --tag canary"
+  },
+  "dependencies": {
+    "@availity/authorize": "^4.1.0",
+    "@availity/mui-block-ui": "^0.1.10",
+    "@tanstack/react-query": "^4.36.1"
+  },
+  "devDependencies": {
+    "@mui/material": "^5.15.15",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "@mui/material": "^5.11.9",
+    "react": ">=16.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,43 @@
+{
+  "name": "mui-authorize",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/authorize/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "eslintConfig": ".eslintrc.json",
+        "lintFilePatterns": ["packages/authorize/**/*.{js,ts}"],
+        "silent": false,
+        "fix": false,
+        "cache": true,
+        "cacheLocation": "./node_modules/.cache/authorize/.eslintcache",
+        "maxWarnings": -1,
+        "quiet": false,
+        "noEslintrc": false,
+        "hasTypeAwareRules": true,
+        "cacheStrategy": "metadata"
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/authorize"],
+      "options": {
+        "jestConfig": "packages/authorize/jest.config.js",
+        "passWithNoTests": true
+      }
+    },
+    "version": {
+      "executor": "@jscutlery/semver:version",
+      "options": {
+        "preset": "conventional",
+        "commitMessageFormat": "chore({projectName}): release version ${version} [skip ci]",
+        "tagPrefix": "@availity/{projectName}@",
+        "trackDeps": true,
+        "skipCommitTypes": ["docs"]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './lib/Authorize';

package/src/lib/Authorize.stories.tsx

@@ -0,0 +1,61 @@
+// Each exported component in the package should have its own stories file
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { Authorize, AuthorizeProps } from '..';
+import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
+import Alert from '@mui/material/Alert';
+
+const meta: Meta<typeof Authorize> = {
+  title: 'Components/Authorize/Authorize',
+  component: Authorize,
+  tags: ['autodocs'],
+  decorators: [
+    (Story: () => JSX.Element) => (
+      <QueryClientProvider client={new QueryClient()}>
+        <Story />
+      </QueryClientProvider>
+    ),
+  ],
+  args: {
+    permissions: ['1234'],
+    parameters: {
+      organizationId: '1111',
+      region: true,
+    },
+    queryOptions: {
+      refetchOnWindowFocus: false,
+    },
+    unauthorized: 'You are not authorized to see this content.',
+    children: 'You are authorized to see this content.',
+    negate: false,
+    loader: true,
+  },
+  argTypes: {
+    children: {
+      control: 'text',
+    },
+    unauthorized: {
+      control: 'text',
+    },
+  },
+};
+
+export default meta;
+
+export const _Authorize: StoryObj<typeof Authorize> = {
+  render: ({children, unauthorized, ...args}: AuthorizeProps) => (
+    <div>
+      <p>
+        For this demo, the following permissions are granted: 1234, 2345, 3456, 4567, 5678, 6789. You can use the knobs
+        to see what the component will do when you set the required permissions to various things.
+      </p>
+      <hr />
+      <Authorize
+        unauthorized={<Alert severity="error">{unauthorized}</Alert>}
+        {...args}
+      >
+        <Alert severity="success">{children}</Alert>
+      </Authorize>
+    </div>
+  ),
+};

package/src/lib/Authorize.test.tsx

@@ -0,0 +1,196 @@
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { server } from '@availity/mock/src/lib/server';
+import { Authorize } from './Authorize';
+
+describe('Authorize', () => {
+  const queryClient = new QueryClient();
+
+  // start msw server
+  beforeAll(() => server.listen());
+
+  // clear cache and reset msw handlers
+  afterEach(() => {
+    queryClient.clear();
+    server.resetHandlers();
+  });
+
+  // terminate the server
+  afterAll(() => server.close());
+
+  test('should render authorized content', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']} loader>
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render unauthorized content', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['12345']} unauthorized="You do not have permission to see this" />
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You do not have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render authorized with array of permissions', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize
+          permissions={['1234', '2345', ['3456', '4567']]}
+          unauthorized="You do not have permission to see this"
+        >
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render negate permissions', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']} negate unauthorized="You do not have permission to see this">
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You do not have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render authorized with correct organizationId', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']} parameters={{organizationId:"1111"}} unauthorized="You do not have permission to see this">
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render unauthorized with incorrect organizationId', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']} parameters={{organizationId:"1112"}} unauthorized="You do not have permission to see this">
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You do not have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render authorized with correct customerId', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']} parameters={{customerId:"1194"}} unauthorized="You do not have permission to see this">
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render unauthorized with incorrect customerId', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']}  parameters={{customerId:"1193"}} unauthorized="You do not have permission to see this">
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You do not have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render authorized with correct resources', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize
+          permissions={['1234']}
+          parameters={{customerId:"1194", resources: ['2']}}
+          unauthorized="You do not have permission to see this"
+        >
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('should render unauthorized with incorrect resources', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize
+          permissions={['1234']}
+          parameters={{customerId:"1194", resources: ['5']}}
+          unauthorized="You do not have permission to see this"
+        >
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('You do not have permission to see this')).toBeDefined();
+    });
+  });
+
+  test('shows BlockUi while fetching permissions', async () => {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Authorize permissions={['1234']} loader>
+          You have permission to see this
+        </Authorize>
+      </QueryClientProvider>
+    );
+    const loadingElements = screen.getAllByText('loading');
+
+    // Filter out the visible one
+    const visibleLoadingElement = loadingElements.find((element) => {
+      // Get computed style of the element
+      const style = window.getComputedStyle(element);
+
+      // Return true if the element is visible
+      return style && style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+    });
+    expect(visibleLoadingElement).toBeInTheDocument();
+
+    // Once data has been fetched, the BlockUi component should no longer be visible
+    await waitFor(() => expect(visibleLoadingElement).not.toBeVisible());
+    await waitFor(() => expect(screen.getByText('You have permission to see this')).toBeInTheDocument());
+  });
+});

package/src/lib/Authorize.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import type { ReactNode } from 'react';
+import { BlockUi } from '@availity/mui-block-ui';
+
+import { useAuthorize, UseAuthorizeProps } from '@availity/authorize';
+
+export type AuthorizeProps = {
+  /** The content that renders when the user does have the permissions required. */
+  children?: ReactNode;
+  /** When true, BlockUi is used when loading the permissions. When a node, that node is rendered instead of BlockUi when loading the permissions. When false, nothing is rendered when loading the permissions. Default: true. */
+  loader?: boolean | ReactNode;
+  /** Negate the authorization. If the user does have the permissions specified, they are considered "unauthorized" (shown the unauthorized prop content). If the user does not have the permissions specified, they are considered "authorized" (shown the children prop content) */
+  negate?: boolean;
+  /** The content that renders when the user does not have the permissions required. */
+  unauthorized?: ReactNode;
+// } & Pick<UseAuthorizeProps, 'permissions' | 'queryOptions'> & UseAuthorizeProps['parameters'];
+} & UseAuthorizeProps;
+
+/** Component for showing content based on the user's permissions. Wrap this component around content you only want specific users to see.
+ *
+ * The `useAuthorize` hook utilizes [react-query](https://tanstack.com/query/v4/docs/framework/react/overview) to handle data fetching.
+ * This means you must add a [QueryClientProvider](https://tanstack.com/query/v4/docs/framework/react/reference/QueryClientProvider)
+ * to your app if you do not already have one.
+ *
+ * The default setup should cover most use-cases. However, there are 2 query options we recommend looking into
+ * in order to determine what is correct for your app. These settings are `refetchOnWindowFocus` and
+ * `staleTime`. The first option sets whether the to refetch the query when the window is focused, and
+ * the other is the default marker for how long the query is valid.
+ */
+export const Authorize = ({
+  loader = true,
+  negate = false,
+  children = null,
+  unauthorized = null,
+  permissions,
+  parameters = {},
+  queryOptions
+}: AuthorizeProps): JSX.Element | null => {
+  const { authorized, isLoading } = useAuthorize(permissions, parameters, queryOptions);
+
+  if (isLoading) {
+    if (loader) return loader === true ? <BlockUi blocking /> : <>{loader}</>;
+    return null;
+  }
+
+  // show children when authorized or negate is exclusively true
+  if ((authorized || negate) && !(authorized && negate)) {
+    return <>{children}</>;
+  }
+
+  return <>{unauthorized}</>;
+};

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["."],
+  "exclude": ["dist", "build", "node_modules"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node", "@testing-library/jest-dom"],
+    "allowJs": true
+  },
+  "include": ["**/*.test.js", "**/*.test.ts", "**/*.test.tsx", "**/*.d.ts"]
+}