@sqrzro/admin 1.0.0-beta.1

package/docs/guides/02-configuration.story.mdx

@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Configuration" />
+
+# Configuration
+
+The config file is located at `src/config/index.js`. Below is a full list of every configuration option available:
+
+## auth
+
+```jsx
+auth: {
+    identifier?: string;
+    identifierLabel?: string;
+    tfa?: boolean;
+} | null;
+```
+
+By default, the login form uses a field name of `username` for the identifier. However, there might be situations where you would want to use `email` or something else. In that instance, you can set `auth.identifier` (the field name) and `auth.identifierLabel` (the field label) to set an alternative.
+
+`tfa` (set to false by default) defines whether or not your backend API supports two-factor authentication.
+
+## Logo
+
+```jsx
+Logo: React.ComponentType<{ isReverse?: boolean }> | null;
+```
+
+If not null, `Logo` is a React component that returns an image. It has only one prop - `isReverse`. If this is set to true, the component should return a white image. This is used on the login and password reset forms. When `isReverse` is set to false, the component should return a dark image, which is used in the top corner of the internal pages. In both instances, the logo sits on top of the colour defined in the `style.brand` configuration option.
+
+## name
+
+```jsx
+name: string;
+```
+
+The name of the site. This is the only config option that is required, and is used in the page titles.
+
+## navigation
+
+```
+navigation: (NavigationObject | string)[];
+```
+
+An array of items that will be in the primary navigation of the site. The item can either be a ‘-’, in which case a divider will be rendered, or a `NavigationObject` which is defined as:
+
+```
+NavigationObject {
+    label: string;
+    to?: string | null;
+    onClick?: MouseEventHandler<HTMLAnchorElement | HTMLButtonElement>;
+    permission?: string;
+}
+```
+
+Technically the only thing a `NavigationObject` requires is a `label`, which will be the text that is displayed on the link. The object will then need one of two things - a `to` value, which will point to the URL you would like the link to go, or a `onClick` value, which will define what function is triggered when the link is clicked. It is entirely possible to include both of these options.
+
+`permission` controls which admin user can or can’t see the particular object. Permissions are explained in more detail on the [API Integration page](/story/guides-integration-with-api--page).
+
+## paths
+
+```
+paths: { api?: string; app?: string };
+```
+
+The `paths.api` defines where your backend API is located. As you can see from the config file, by default the API path is set to read from an ‘env.js’ file included in the root. This file is excluded from git, and allows you to define different backend URLs for the same admin panel in different environments. I.e. local, staging, and production versions can all point to different backend URLs.
+
+The `paths.app` defines where your application itself is located, assuming it is not at the root of a domain. This can usually be omitted but if, for example, you would like your application to be hosted at https://example.com/admin/, you would define `paths.app` as `admin`. This would ensure all links and redirects within the app go to the right place.
+
+## style
+
+```
+style: { brand?: string; layout?: string } | null;
+```
+
+The `style.brand` value is simply a hexcode which defines the background colour for the logos throughout the site.
+
+`style.layout` can either be omitted, or be defined as ‘topbar’. If omitted, the layout of the application will appear in a traditional dashboard way - with the navigation running vertically along the left hand side of the page, and the content to the right. If, however, it is defined as ‘topbar’, the navigation runs horizontally across the top of the page.
+
+More style options may be added in future versions. However, it is an important tenet of Square Zero Admin that it does not offer too much customisation, in order to allow developers to focus on building pages rather than concerning themselves with style decisions.

package/docs/guides/03-pages.story.mdx

@@ -0,0 +1,18 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Pages & Routing" />
+
+# Pages & Routing
+
+As Square Zero Admin is built on top of Next.js, it uses the same method for routing. You can read the [full documentation for Next.js routing](https://nextjs.org/docs/basic-features/pages) here, but in essence, any `.tsx` file you place in the `src/pages` folder will become a route. For example, a file at `src/pages/lorem.tsx` will be accessible at `/lorem`. The most basic admin page would look something like this:
+
+```
+import React from 'react';
+import { Scene } from 'squarezero-admin';
+
+const ExampleScene = () => (
+    <Scene title="Example Scene">Here is an example of some content</Scene>
+);
+
+export default ExampleScene;
+```

package/docs/guides/04-integration.story.mdx

@@ -0,0 +1,33 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Integration with API" />
+
+# Integration with API
+
+Although not required, in almost all circumstances Square Zero Admin is going to be interacting with a backend API. This guide explains what requests are sent to the API, and what responses are expected back. This should enable you to make sure your backend API will integrate smoothly with your admin system.
+
+*Note: For simplicity, Square Zero Admin's request and response expectations are kept very opinionated, without much room for customisation. However, if this approach is deemed to restrictive to be useful for many projects, some more customisation options will be made available.*
+
+## Authentication
+
+Square Zero Admin makes use of JSON Web Tokens (JWT) for Authentication. JWT are an open, industry standard (RFC 7519) method for representing claims securely between two parties. When an admin user successfully logs in, the backend should pass a token back in the response. Square Zero Admin then stores this, and passes it up as an `Authorization` header in the next request. The backend should then check this header, ensure the token is valid, and only then respond with the requested data. The response should also contain an `Authorization` header with a new token, which Square Zero Admin will store and use for the next request, and so on.
+
+### Login
+
+In order to login, Square Zero Admin will expect to be able to `POST` to `/tokens` with the following parameters:
+
+```jsx
+{"username": "lorem", "password": "ipsum"}
+```
+
+If the user's details are correct, the backend should respond with a status of 200, and with a newly generated JWT:
+
+```jsx
+{ "token": "areallylongstringofcharacters" }
+```
+
+If they are incorrect, the backend should respond with a status of 422, and an object of errors:
+
+```jsx
+{ "errors": { "email": "An error message" } }
+```

package/docs/guides/a11y.story.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Accessibility" />
+
+# Accessibility
+
+Coming soon...

package/docs/guides/theming.story.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Guides/Theming" />
+
+# Theming
+
+Coming soon...

package/docs/introduction.story.mdx

@@ -0,0 +1,17 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Overview/Introduction" />
+
+<svg height="40" width="40"><rect fill="red" x="0" y="0" height="40" width="40" /></svg>
+
+---
+
+# Introduction
+
+Square Zero Admin is a collection of opinionated components, hooks, services and utilities that lets you very quickly build admin systems in React. This guide will help you setup an admin system, as well as acting as a comprehensive reference for all the elements available in the system.
+
+[Click here to get started](/story/guides-installation--page)
+
+## A Note on Beta
+
+Currently, the latest version of Square Zero Admin is `beta`. Although the package is well tested, and used on a number of production sites, with the current lack of documentation it would be unfair to describe it as ‘production-ready’, unless being used by the developers of the package. Work on complete documentation is underway and a true version `1.0.0` should be available in the near future.

package/jest.config.js

@@ -0,0 +1,19 @@
+module.exports = {
+    globals: {
+        'ts-jest': { isolatedModules: true },
+    },
+    moduleNameMapper: {
+        '@components/(.*)': '<rootDir>/src/components/$1',
+        '@core/(.*)': '<rootDir>/src/core/$1',
+        '@filters/(.*)': '<rootDir>/src/filters/$1',
+        '@hooks/(.*)': '<rootDir>/src/hooks/$1',
+        '@services/(.*)': '<rootDir>/src/services/$1',
+        '@utility/(.*)': '<rootDir>/src/utility/$1',
+        '\\.css$': 'identity-obj-proxy',
+        'modern-normalize': 'identity-obj-proxy',
+    },
+    preset: 'ts-jest',
+    setupFilesAfterEnv: ['<rootDir>/tests/setupFilesAfterEnv.js'],
+    testEnvironment: 'jsdom',
+    testMatch: ['**/?(*.)+(spec).ts?(x)'],
+};

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@sqrzro/admin",
+  "version": "1.0.0-beta.1",
+  "description": "Useful components, services, and tools for React projects",
+  "main": "dist/index.js",
+  "typings": "dist/types/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./index.css": "./dist/index.css"
+  },
+  "author": "Richard Carter",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sqrzro/squarezero-admin"
+  },
+  "scripts": {
+    "build:app": "rollup -c",
+    "build:docs": "build-storybook",
+    "build:license": "node ./scripts/update-license",
+    "build:exports": "node ./scripts/create-exports",
+    "build:types": "tsc --emitDeclarationOnly --project tsconfig.types.json && tsc-alias -p tsconfig.types.json",
+    "build": "yarn run build:exports && yarn run build:app && yarn run build:types && yarn run build:license",
+    "dev": "yarn run build:app --watch",
+    "docs": "start-storybook -p 6006",
+    "lint:css": "stylelint \"src/**/*.css\"",
+    "lint:ts": "eslint \"src/**/*.ts\" \"src/**/*.tsx\"",
+    "lint": "tsc --noEmit && yarn run lint:ts && yarn run lint:css",
+    "prepublish": "yarn run build",
+    "prettier": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "start": "yarn run dev",
+    "test": "jest --runInBand"
+  },
+  "dependencies": {
+    "@heroicons/react": "^1.0.4",
+    "@sqrzro/utility": "^1.0.1",
+    "classnames": "^2.3.1",
+    "date-fns": "^2.25.0",
+    "deepmerge": "^4.2.2",
+    "modern-normalize": "^1.1.0",
+    "next": "^12.0.8",
+    "prop-types": "^15.7.2",
+    "regenerator-runtime": "^0.13.9",
+    "use-deep-compare-effect": "^1.8.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.15.8",
+    "@babel/plugin-proposal-class-properties": "^7.14.5",
+    "@babel/preset-env": "^7.15.8",
+    "@babel/preset-react": "^7.14.5",
+    "@rollup/plugin-node-resolve": "^13.0.5",
+    "@rollup/plugin-typescript": "^8.2.5",
+    "@sqrzro/eslint-plugin": "^1.1.0",
+    "@storybook/addon-actions": "^6.4.3",
+    "@storybook/addon-docs": "^6.4.3",
+    "@storybook/addon-essentials": "^6.4.3",
+    "@storybook/addon-links": "^6.4.3",
+    "@storybook/addon-postcss": "^2.0.0",
+    "@storybook/builder-webpack5": "^6.4.3",
+    "@storybook/manager-webpack5": "^6.4.3",
+    "@storybook/react": "^6.4.3",
+    "@storybook/theming": "^6.4.13",
+    "@testing-library/dom": "^8.11.1",
+    "@testing-library/jest-dom": "^5.15.1",
+    "@testing-library/react": "^12.1.2",
+    "@testing-library/react-hooks": "^7.0.2",
+    "@testing-library/user-event": "^13.5.0",
+    "@types/airbnb-prop-types": "^2.13.2",
+    "@types/jest": "^27.0.2",
+    "@types/prop-types": "^15.7.4",
+    "autoprefixer": "^10.3.7",
+    "babel-loader": "^8.2.2",
+    "babel-plugin-module-resolver": "^4.1.0",
+    "cors": "^2.8.5",
+    "css-loader": "^6.4.0",
+    "eslint": "^8.10.0",
+    "identity-obj-proxy": "^3.0.0",
+    "jest": "^27.2.5",
+    "jest-fetch-mock": "^3.0.3",
+    "mockdate": "^3.0.5",
+    "npm-run-all": "^4.1.5",
+    "postcss": "^8.3.9",
+    "postcss-loader": "^6.1.1",
+    "postcss-preset-env": "^7.0.0",
+    "prettier": "^2.5.0",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "rollup": "^2.58.0",
+    "rollup-plugin-postcss": "^4.0.1",
+    "storybook": "^6.4.3",
+    "style-loader": "^3.3.0",
+    "stylelint": "^13.13.1",
+    "stylelint-config-standard": "^22.0.0",
+    "ts-jest": "^27.0.5",
+    "tsc-alias": "^1.5.0",
+    "tslib": "^2.3.1",
+    "typescript": "^4.4.3",
+    "webpack": "^5.58.2"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    plugins: [require('postcss-preset-env')({ importFrom: 'src/styles/variables.css', stage: 1 })],
+};

package/rollup.config.js

@@ -0,0 +1,36 @@
+import postcss from 'rollup-plugin-postcss';
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from '@rollup/plugin-typescript';
+
+const globals = {
+    '@heroicons/react': '@heroicons/react',
+    '@sqrzro/utility': '@sqrzro/utility',
+    classnames: 'classNames',
+    'date-fns': 'dateFns',
+    deepmerge: 'deepmerge',
+    'next/app': 'NextApp',
+    'next/document': 'NextDocument',
+    'next/head': 'NextHead',
+    'next/link': 'NextLink',
+    'next/router': 'NextRouter',
+    'prop-types': 'PropTypes',
+    react: 'React',
+    'react-router': 'react-router',
+    'regenerator-runtime': 'regeneratorRuntime',
+    'use-deep-compare-effect': 'useDeepCompareEffect',
+};
+
+const config = {
+    input: 'src/index.ts',
+    output: {
+        file: 'dist/index.js',
+        format: 'umd',
+        globals,
+        name: 'squarezero-admin',
+        sourcemap: true,
+    },
+    external: Object.keys(globals),
+    plugins: [resolve(), typescript(), postcss({ extract: true })],
+};
+
+export default config;

package/scripts/create-exports.js

@@ -0,0 +1,74 @@
+const fs = require('fs');
+const path = require('path');
+
+const exportStrings = [];
+
+const filterMocksAndSpecs = (files) =>
+    files.filter((file) => !file.match(/__mocks__/u) && !file.match(/\.spec\./u));
+
+/*
+ * Utility
+ * Services from `@sqrzro/utility` should be imported and then immeadiately exported, so users
+ * can just import everything from `squarezero-admin`, without having to worry about where it's
+ * actually come from
+ */
+
+const utilities = ['ApiService', 'AuthService', 'EventService', 'StorageService'];
+
+exportStrings.push(`export { ${utilities.join(', ')} } from '@sqrzro/utility';`);
+
+// Components
+
+const components = fs.readdirSync(path.resolve(__dirname, '../src/components'));
+
+components.forEach((file) => {
+    exportStrings.push(`export * from './components/${file}';`);
+    exportStrings.push(`export { default as ${file} } from './components/${file}';`);
+});
+
+// Core (Types Only)
+
+const core = fs.readdirSync(path.resolve(__dirname, '../src/core'));
+
+core.forEach((file) => {
+    exportStrings.push(`export * from './core/${file}';`);
+});
+
+// Hooks
+
+const hooks = fs.readdirSync(path.resolve(__dirname, '../src/hooks'));
+
+filterMocksAndSpecs(hooks).forEach((file) => {
+    const name = file.replace(/\.ts$/u, '');
+    exportStrings.push(`export * from './hooks/${name}';`);
+    exportStrings.push(`export { default as ${name} } from './hooks/${name}';`);
+});
+
+// Services
+
+const services = fs.readdirSync(path.resolve(__dirname, '../src/services'));
+
+filterMocksAndSpecs(services).forEach((file) => {
+    const name = file.replace(/\.tsx?$/u, '');
+    exportStrings.push(`export * from './services/${name}';`);
+    exportStrings.push(`export { default as ${name} } from './services/${name}';`);
+});
+
+// Write
+
+const allExportStrings = exportStrings.join('\n');
+const content = [
+    '/*',
+    " * This file has been generated by 'scripts/create-exports'.",
+    ' * Any changes made directly to this file will be overwritten.',
+    ' */',
+    '',
+    "import 'regenerator-runtime/runtime.js';",
+    '',
+    "export * from './utility/interfaces';",
+    "export { default as createApp } from './utility/create-app';",
+    '',
+    allExportStrings,
+].join('\n');
+
+fs.writeFileSync(path.resolve(__dirname, '../src/index.ts'), `${content}\n`);

package/scripts/update-license.js

@@ -0,0 +1,8 @@
+const fs = require('fs');
+const path = require('path');
+
+const license = path.resolve(__dirname, '../LICENSE');
+const content = fs.readFileSync(license, 'utf8');
+const updated = content.replace(/^Copyright \d{4}/u, `Copyright ${new Date().getFullYear()}`);
+
+fs.writeFileSync(license, updated);

package/squarezero.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    template: 'react',
+    styles: 'postcss',
+    ts: true,
+};

package/src/components/Alert/Alert.module.css

@@ -0,0 +1,50 @@
+.root {
+    bottom: 0;
+    left: 0;
+    position: fixed;
+    right: 0;
+    top: 0;
+    z-index: 10;
+}
+
+.overlay {
+    background-color: var(--clr-grey900);
+    bottom: 0;
+    left: 0;
+    position: absolute;
+    right: 0;
+    top: 0;
+}
+
+.panel {
+    left: calc(50% - 30rem);
+    position: absolute;
+    top: 15%;
+    width: 60rem;
+}
+
+.title {
+    border-bottom: .1rem var(--clr-grey300) solid;
+    color: var(--clr-grey600);
+    font-size: var(--fs-lrg);
+    font-weight: var(--fw-bold);
+    line-height: 1;
+    margin-bottom: 3rem;
+    margin-left: -.2rem;
+    margin-top: -.5rem;
+    padding-bottom: 2rem;
+}
+
+.actions {
+    border-top: .1rem var(--clr-grey300) solid;
+    display: flex;
+    flex-direction: row-reverse;
+    margin-bottom: -1rem;
+    margin-top: 3rem;
+    padding-top: 2rem;
+
+    & > * {
+        margin-left: 1rem;
+        width: auto;
+    }
+}

package/src/components/Alert/Alert.spec.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import Alert from './index';
+
+describe('Alert', () => {
+    it('should render', () => {
+        render(<Alert title="Lorem">Lorem</Alert>);
+    });
+
+    it('should render defaults', () => {
+        render(<Alert title="Lorem">Lorem</Alert>);
+
+        const alert = screen.getByRole('alert');
+        const heading = screen.getByRole('heading');
+        const buttons = screen.queryAllByRole('button');
+
+        expect(heading).toHaveClass('title');
+        expect(heading).toHaveTextContent(/^Lorem$/u);
+
+        expect(alert).toHaveTextContent('LoremLorem');
+        expect(buttons).toHaveLength(0);
+    });
+
+    it('should render variant', () => {
+        render(
+            <Alert title="Lorem" variant="primary">
+                Lorem
+            </Alert>
+        );
+
+        const heading = screen.getByRole('heading');
+        expect(heading).toHaveClass('title titlePrimary');
+    });
+
+    it('should render actions', () => {
+        const mockFn = jest.fn();
+        const actions = [
+            { label: 'Lorem', onClick: mockFn },
+            { label: 'Ipsum', onClick: mockFn, variant: 'secondary' as const },
+        ];
+
+        render(
+            <Alert actions={actions} title="Lorem">
+                Lorem
+            </Alert>
+        );
+
+        const buttons = screen.queryAllByRole('button');
+
+        expect(buttons).toHaveLength(2);
+
+        expect(buttons[0]).toHaveTextContent(/^Lorem$/u);
+
+        expect(mockFn).toHaveBeenCalledTimes(0);
+        userEvent.click(buttons[0]);
+        expect(mockFn).toHaveBeenCalledTimes(1);
+
+        expect(buttons[1]).toHaveTextContent(/^Ipsum$/u);
+        expect(buttons[1]).toHaveClass('root rootSecondary');
+    });
+});

package/src/components/Alert/Alert.story.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+
+import StorybookPanel from '@utility/StorybookPanel';
+
+import Alert from './index';
+
+export default { title: 'Components/Alert', component: Alert };
+
+const mockActions = [{ label: 'Lorem Ipsum', onClick: (): null => null }];
+
+export const Default = (): React.ReactElement => (
+    <StorybookPanel>
+        <Alert title="Lorem">Lorem ipsum dolor sit amet, consectetur adipiscing elit</Alert>
+    </StorybookPanel>
+);
+
+export const WithActions = (): React.ReactElement => (
+    <StorybookPanel>
+        <Alert actions={mockActions} title="Lorem">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit
+        </Alert>
+    </StorybookPanel>
+);

package/src/components/Alert/index.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import classNames from 'classnames';
+import PropTypes from 'prop-types';
+
+import { ucwords } from '@sqrzro/utility';
+
+import Button from '@components/Button';
+import Panel from '@core/Panel';
+
+import type { SimpleAction, StyleVariant } from '@utility/interfaces';
+
+import styles from './Alert.module.css';
+
+interface AlertProps {
+    actions?: SimpleAction[];
+    children: React.ReactNode;
+    title: string;
+    variant?: StyleVariant;
+}
+
+const Alert: React.FunctionComponent<AlertProps> = ({ actions, children, title, variant }) => (
+    <div className={styles.root}>
+        <div className={styles.overlay} />
+        <aside className={styles.panel} role="alert">
+            <Panel isPadded>
+                <h3
+                    className={classNames(
+                        styles.title,
+                        variant && styles[`title${ucwords(variant)}`]
+                    )}
+                    role="heading"
+                >
+                    {title}
+                </h3>
+                {children}
+                {actions?.length ? (
+                    <footer className={styles.actions}>
+                        {actions.map((action) => (
+                            <Button
+                                key={action.label}
+                                isDisabled={action.isDisabled}
+                                onClick={action.onClick}
+                                variant={action.variant}
+                            >
+                                {action.label}
+                            </Button>
+                        ))}
+                    </footer>
+                ) : null}
+            </Panel>
+        </aside>
+    </div>
+);
+
+Alert.propTypes = {
+    children: PropTypes.node.isRequired,
+    title: PropTypes.string.isRequired,
+    actions: PropTypes.arrayOf(
+        PropTypes.shape({
+            label: PropTypes.string.isRequired,
+            onClick: PropTypes.func.isRequired,
+        }).isRequired
+    ),
+    variant: PropTypes.oneOf(['primary', 'secondary', 'tertiary', 'danger']),
+};
+
+export default Alert;

package/src/components/Allow/Allow.spec.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+import type { Config } from '@hooks/useAppContext';
+
+import Allow from './index';
+
+jest.mock(
+    '@hooks/useAppContext',
+    () => (): Config => ({
+        me: { name: 'Lorem', permissions: ['lorem'] },
+        name: 'Lorem',
+        navigation: [],
+        paths: {},
+    })
+);
+
+describe('Allow', () => {
+    it('should render', () => {
+        render(<Allow>Lorem</Allow>);
+    });
+
+    it('should render defaults', () => {
+        render(<Allow>Lorem</Allow>);
+        expect(screen.getByText(/^Lorem$/u)).toBeInTheDocument();
+    });
+
+    it('should render with no permission', () => {
+        render(<Allow permission="ipsum">Lorem</Allow>);
+        expect(screen.queryByText(/^Lorem$/u)).not.toBeInTheDocument();
+    });
+
+    it('should render with permission', () => {
+        render(<Allow permission="lorem">Lorem</Allow>);
+        expect(screen.getByText(/^Lorem$/u)).toBeInTheDocument();
+    });
+});