xenopomp-essentials 0.3.1 → 0.3.3

package/src/eslint/configs/markdown.ts

@@ -0,0 +1,30 @@
+import { GLOB_MARKDOWN_CODE } from '@antfu/eslint-config';
+import type { TypedFlatConfigItem } from '@antfu/eslint-config';
+
+import { AUTHOR_NAME_LOWER } from '../prefixes';
+
+export async function markdown(): Promise<TypedFlatConfigItem[]> {
+  return [
+    {
+      name: `${AUTHOR_NAME_LOWER}:markdown`,
+      files: [GLOB_MARKDOWN_CODE],
+      rules: {
+        'import/no-unresolved': 'off',
+        'unused-imports/no-unused-imports': 'off',
+        'unused-imports/no-unused-vars': 'off',
+        'no-alert': 'off',
+        'no-console': 'off',
+        'no-restricted-imports': 'off',
+        'no-undef': 'off',
+        'no-unused-expressions': 'off',
+        'no-unused-vars': 'off',
+        'antfu/no-cjs-exports': 'off',
+        'antfu/no-ts-export-equal': 'off',
+        'ts/no-redeclare': 'off',
+        'ts/no-unused-vars': 'off',
+        'ts/no-var-requires': 'off',
+        'ts/consistent-type-imports': 'off',
+      },
+    },
+  ];
+}

package/src/eslint/configs/next.ts

@@ -0,0 +1,40 @@
+import type { TypedFlatConfigItem } from '@antfu/eslint-config';
+import { interopDefault } from '@antfu/eslint-config';
+
+import { AUTHOR_NAME_LOWER } from '../prefixes';
+
+export async function next(): Promise<TypedFlatConfigItem[]> {
+  // @ts-expect-error un typed
+  const next = await interopDefault(import('@next/eslint-plugin-next'));
+
+  return [
+    {
+      name: `${AUTHOR_NAME_LOWER}:next`,
+      plugins: { '@next/next': next },
+      rules: {
+        '@next/next/google-font-display': 'warn',
+        '@next/next/google-font-preconnect': 'warn',
+        '@next/next/next-script-for-ga': 'warn',
+        '@next/next/no-async-client-component': 'warn',
+        '@next/next/no-before-interactive-script-outside-document': 'warn',
+        '@next/next/no-css-tags': 'warn',
+        '@next/next/no-head-element': 'warn',
+        '@next/next/no-html-link-for-pages': 'warn',
+        '@next/next/no-img-element': 'warn',
+        '@next/next/no-page-custom-font': 'warn',
+        '@next/next/no-styled-jsx-in-document': 'warn',
+        '@next/next/no-sync-scripts': 'warn',
+        '@next/next/no-title-in-document-head': 'warn',
+        '@next/next/no-typos': 'warn',
+        '@next/next/no-unwanted-polyfillio': 'warn',
+        // errors
+        '@next/next/inline-script-id': 'error',
+        '@next/next/no-assign-module-variable': 'error',
+        '@next/next/no-document-import-in-page': 'error',
+        '@next/next/no-duplicate-head': 'error',
+        '@next/next/no-head-import-in-document': 'error',
+        '@next/next/no-script-component-in-head': 'error',
+      },
+    },
+  ];
+}

package/src/eslint/configs/old.ts

@@ -0,0 +1,67 @@
+import type { TypedFlatConfigItem } from '@antfu/eslint-config';
+import globals from 'globals';
+
+import { AUTHOR_NAME_LOWER } from '../prefixes';
+
+export async function old(): Promise<TypedFlatConfigItem[]> {
+  return [
+    {
+      name: `${AUTHOR_NAME_LOWER}:old_config`,
+      languageOptions: {
+        globals: {
+          ...globals.browser,
+          ...globals.jquery,
+          ...globals.node,
+
+          // Rewrite globals anyway
+          document: 'readonly',
+          navigator: 'readonly',
+          window: 'readonly',
+        },
+      },
+
+      // Ignore patterns
+      ignores: [
+        '**/.next/*',
+        '**/node_modules/*',
+        '**/.github/*',
+        'cypress',
+        '**/__tests__/e2e/*',
+        '*.json',
+        '**/*.d.ts',
+        '.eslintrc.js',
+        'eslint.config.js',
+        '.prettierrc',
+        '.stylelintrc.js',
+        'tsconfig.json',
+        'package.json',
+        '*.md',
+        '*.config.ts',
+        '*.config.js',
+        '*.md',
+      ],
+    },
+    {
+      name: `${AUTHOR_NAME_LOWER}:rules_breakup_1`,
+      rules: { '@next/next/no-duplicate-head': 'off' },
+    },
+    {
+      name: `${AUTHOR_NAME_LOWER}:rules_breakup_2`,
+      rules: {
+        'style/operator-linebreak': 'off',
+        'test/consistent-test-it': 'off',
+        'test/prefer-lowercase-title': 'off',
+        'style/jsx-quotes': 'off',
+        'style/multiline-ternary': 'off',
+        'style/indent': 'off',
+      },
+      ignores: ['cypress'],
+    },
+    {
+      name: `${AUTHOR_NAME_LOWER}:prettier`,
+      rules: {
+        'antfu/if-newline': 'off',
+      },
+    },
+  ];
+}

package/src/eslint/configs/prettier.ts

@@ -0,0 +1,6 @@
+import type { TypedFlatConfigItem } from '@antfu/eslint-config';
+import recommended from 'eslint-plugin-prettier/recommended';
+
+export async function prettier(): Promise<TypedFlatConfigItem[]> {
+  return [recommended];
+}

package/src/eslint/configs/react.ts

@@ -0,0 +1,18 @@
+import type { TypedFlatConfigItem } from '@antfu/eslint-config';
+import { GLOB_JSX, GLOB_TSX } from '@antfu/eslint-config';
+
+import { AUTHOR_NAME_LOWER } from '../prefixes';
+
+export async function react(): Promise<TypedFlatConfigItem[]> {
+  return [
+    {
+      files: [GLOB_JSX, GLOB_TSX],
+      name: `${AUTHOR_NAME_LOWER}:react`,
+      rules: {
+        'react-refresh/only-export-components': 'off',
+        'react/no-clone-element': 'off',
+        'react/no-missing-component-display-name': 'off',
+      },
+    },
+  ];
+}

package/src/eslint/index.ts

@@ -0,0 +1,7 @@
+import type { Options } from './config';
+import xenopomp from './config';
+
+export type { Options };
+export * from './types';
+
+export default xenopomp;

package/src/eslint/prefixes/author.ts

@@ -0,0 +1,2 @@
+export const AUTHOR_NAME = 'XenoPOMP';
+export const AUTHOR_NAME_LOWER = AUTHOR_NAME.toLowerCase();

package/src/eslint/prefixes/index.ts

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

package/src/eslint/types/configs.ts

@@ -0,0 +1,4 @@
+import type { antfu } from '@antfu/eslint-config';
+
+export type UserConfigItem = Parameters<typeof antfu>[1];
+export type Configs = ReturnType<typeof antfu>;

package/src/eslint/types/custom-config.ts

@@ -0,0 +1,4 @@
+export interface CustomConfig {
+  all?: boolean;
+  next?: boolean;
+}

package/src/eslint/types/index.ts

@@ -0,0 +1,2 @@
+export * from './custom-config';
+export * from './configs';

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './utils';
+export * from './react';

package/src/next/Metrika/Metrika.props.ts

@@ -0,0 +1,11 @@
+export interface MetrikaProps {
+  /**
+   * ID of your Yandex.Metrika`s counter.
+   * Locate at dashboard.
+   */
+  id: number;
+
+  clickMap?: boolean;
+  trackLinks?: boolean;
+  accurateTrackBounce?: boolean;
+}

package/src/next/Metrika/Metrika.tsx

@@ -0,0 +1,56 @@
+import Script from 'next/script';
+import type { FC } from 'react';
+
+import type { MetrikaProps } from './Metrika.props';
+
+/**
+ * This component allows you to use Yandex.Metrika
+ * in your Next.js projects.
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * import { Metrika } from 'xenopomp-essentials/next';
+ *
+ * export default function RootLayout({
+ *   children,
+ * }: {
+ *   children: React.ReactNode
+ * }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <Metrika id={123456789} />
+ *       </head>
+ *       <body>{children}</body>
+ *      </html>
+ *   )
+ * }
+ *
+ * @see https://metrika.yandex.ru
+ */
+export const Metrika: FC<MetrikaProps> = ({
+  id,
+  clickMap = true,
+  trackLinks = true,
+  accurateTrackBounce = true,
+}) => {
+  return (
+    <Script
+      id='metrika-counter'
+      strategy='afterInteractive'
+    >
+      {`   (function(m,e,t,r,i,k,a){m[i]=m[i]||function(){(m[i].a=m[i].a||[]).push(arguments)};
+           m[i].l=1*new Date();
+           for (var j = 0; j < document.scripts.length; j++) {if (document.scripts[j].src === r) { return; }}
+           k=e.createElement(t),a=e.getElementsByTagName(t)[0],k.async=1,k.src=r,a.parentNode.insertBefore(k,a)})
+           (window, document, "script", "https://mc.yandex.ru/metrika/tag.js", "ym");
+        
+           ym(${id}, "init", {
+                clickmap:${clickMap},
+                trackLinks:${trackLinks},
+                accurateTrackBounce:${accurateTrackBounce}
+           });`}
+    </Script>
+  );
+};

package/src/next/ReactScan/ReactScan.tsx

@@ -0,0 +1,33 @@
+import type { FC } from 'react';
+
+/**
+ * Adds react-scan to your Next.js application.
+ * @constructor
+ * @since 0.0.1
+ *
+ * @example
+ * import { ReactScan } from 'xenopomp-essentials/next';
+ *
+ * export default function RootLayout({
+ *   children,
+ * }: {
+ *   children: React.ReactNode
+ * }) {
+ *   return (
+ *     <html lang="en">
+ *       <head>
+ *         <ReactScan />
+ *       </head>
+ *       <body>{children}</body>
+ *      </html>
+ *   )
+ *}
+ */
+export const ReactScan: FC<unknown> = () => {
+  return (
+    <script
+      src='https://unpkg.com/react-scan/dist/auto.global.js'
+      async
+    />
+  );
+};

package/src/next/index.ts

@@ -0,0 +1,2 @@
+export * from './ReactScan/ReactScan';
+export * from './Metrika/Metrika';

package/src/react/hoc/index.ts

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

package/src/react/hoc/jsxDotNotation.tsx

@@ -0,0 +1,38 @@
+import type { FC } from 'react';
+
+import type { EmptyObject } from '@/types';
+
+/**
+ * Creates properly type object with jsxDotNotation.
+ *
+ * @param comp
+ * @param rest
+ *
+ * @example
+ * const FlexComp: FC<PropsWithChildren> = ({ children }) => <div>{children}</div>;
+ * const FlexRow: FC<PropsWithChildren & { short?: boolean }> = ({ children }) => (
+ *   <div>{children}</div>
+ * );
+ * const FlexCol: FC<PropsWithChildren> = ({ children }) => <div>{children}</div>;
+ *
+ * const Flex = jsxDotNotation(FlexComp, {
+ *   Row: FlexRow,
+ *   Col: FlexCol,
+ * });
+ *
+ * const Am = () => {
+ *   return (
+ *     <Flex>
+ *       <Flex.Row short>
+ *         <Flex.Col></Flex.Col>
+ *       </Flex.Row>
+ *     </Flex>
+ *   );
+ * };
+ */
+export function jsxDotNotation<
+  Props = EmptyObject,
+  Rest extends Record<string, FC<any>> = EmptyObject,
+>(comp: FC<Props>, rest: Rest) {
+  return Object.assign(comp, rest);
+}

package/src/react/index.ts

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

package/src/repo-eslint-rules/deep-type-naming.rule.ts

@@ -0,0 +1,49 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+const createRule = ESLintUtils.RuleCreator(
+  () => 'https://github.com/XenoPOMP/xenopomp-essentials-js',
+);
+
+export const deepTypeNamingRule = createRule({
+  name: 'deep-types-naming',
+  defaultOptions: [],
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Naming convention for deep types.',
+    },
+    messages: {
+      invalidName: 'Deep type name have to follow "TypeDeep" convention.',
+    },
+    schema: [],
+  },
+  create(context) {
+    function doesNotFollowConvention(name: string): boolean {
+      // Word Deep not detected. Stop visitor execution.
+      if (!/Deep/.test(name)) {
+        return false;
+      }
+
+      // Word "Deep" is presented inside type declaration name.
+      // Checking for convention.
+      return !/^\w+Deep/.test(name);
+    }
+
+    return {
+      'TSInterfaceDeclaration, TSTypeAliasDeclaration': function (
+        node: TSESTree.TSInterfaceDeclaration | TSESTree.TSTypeAliasDeclaration,
+      ) {
+        const { id } = node;
+
+        if (doesNotFollowConvention(id.name)) {
+          // Report that problem is detected.
+          context.report({
+            messageId: 'invalidName',
+            node: node.id,
+          });
+        }
+      },
+    };
+  },
+});

package/src/repo-eslint-rules/index.ts

@@ -0,0 +1,9 @@
+import { deepTypeNamingRule } from './deep-type-naming.rule';
+
+const plugin = {
+  rules: {
+    'deep-type-naming': deepTypeNamingRule,
+  },
+};
+
+export default plugin;

package/src/schemas/import-meta.schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+const importMetaSchema = z.object({
+  dirname: z.string().optional(),
+});
+
+/**
+ * Validates import.meta object.
+ *
+ * @since 0.0.1
+ */
+export const importMeta = importMetaSchema.parse(import.meta);

package/src/schemas/index.ts

@@ -0,0 +1 @@
+export * from './import-meta.schema';

package/src/types/aliases/AnyObject.ts

@@ -0,0 +1,5 @@
+/**
+ * Matches any object but not arrays, class instances etc.
+ * @since 0.0.1
+ */
+export type AnyObject = Record<PropertyKey, unknown>;

package/src/types/aliases/EmptyObject.ts

@@ -0,0 +1,8 @@
+/**
+ * This type stands for empty object type.
+ *
+ * @since 0.0.1
+ * @example
+ * const message: EmptyObject = { type: string; }; // Will cause error.
+ */
+export type EmptyObject = Record<PropertyKey, never>;

package/src/types/aliases/Fn.ts

@@ -0,0 +1,12 @@
+/**
+ * Simple alias for creating function types. You can use it for type guards
+ * as representation of any function, also you can create cleaner type declarations
+ * for functions.
+ *
+ * @since 0.0.1
+ * @example
+ * type MyFn = Fn<[a: string, b: string], string>;
+ */
+export type Fn<Args extends any[] = any[], Res = unknown> = (
+  ...args: Args
+) => Res;

package/src/types/aliases/index.ts

@@ -0,0 +1,3 @@
+export * from './AnyObject';
+export * from './EmptyObject';
+export * from './Fn';

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from './aliases';
+export * from './next';
+export * from './react';
+export * from './utilities';

package/src/types/next/NextParams.ts

@@ -0,0 +1,26 @@
+type ParamObj<P extends string> = Record<P, string>;
+
+/**
+ * Represents Next.js routing params.
+ * @since 0.0.1
+ */
+export interface NextParams<P extends string> {
+  params: ParamObj<P>;
+}
+
+/**
+ * Represents Next.js routing search params.
+ * @since 0.0.1
+ */
+export interface NextSearchParams<P extends string> {
+  searchParams: ParamObj<P>;
+}
+
+/**
+ * This type describes Next error page params.
+ * @since 0.0.1
+ */
+export interface NextErrorParams<E extends Error = any> {
+  error: E;
+  reset: () => void;
+}

package/src/types/next/index.ts

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

package/src/types/react/AnyFc.ts

@@ -0,0 +1,6 @@
+import type { FC } from 'react';
+
+/**
+ * Matches any proper React component.
+ */
+export type AnyFC = FC<unknown>;

package/src/types/react/AsyncFC.ts

@@ -0,0 +1,16 @@
+import type { FC, ReactNode } from 'react';
+
+import type { ReplaceReturnType } from '@/types';
+
+/**
+ * Same as **FC** (or FunctionalComponent), but it returns Promise.
+ *
+ * @since 0.0.1
+ * @example
+ * const Header: AsyncFC<HeaderProps> = async ({}) => {
+ *   // Do async stuff here...
+ *
+ *   return <div></div>;
+ * };
+ */
+export type AsyncFC<T = unknown> = ReplaceReturnType<FC<T>, Promise<ReactNode>>;

package/src/types/react/DataAttributes.ts

@@ -0,0 +1,21 @@
+/**
+ * Type that represents data-{attr} keys.
+ */
+type Attribute = `data-${string}`;
+
+/**
+ * Matches any proper data-{attr} keys.
+ */
+type DataAttributeShape = Record<Attribute, any>;
+
+/**
+ * Represents React`s data-{attr} properties for components.
+ *
+ * @example
+ * type AdditionalAttributes = DataAttributes<{ 'data-disabled': boolean }>;
+ *
+ * const attrs: AdditionalAttributes = {
+ *   'data-disabled': false, // this attr is required
+ * };
+ */
+export type DataAttributes<Shape extends DataAttributeShape> = Shape;

package/src/types/react/FCProps.ts

@@ -0,0 +1,19 @@
+import type { FC } from 'react';
+
+/**
+ * @deprecated use {@link FCProps} instead.
+ */
+export type FcProps<Comp> = FCProps<Comp>;
+
+/**
+ * Extracts type of props from FC type.
+ *
+ * @since 0.0.1
+ * @example
+ * type Props = FcProps<FC<{ align?: boolean }>>;
+ * //   ^? { align?: boolean }
+ *
+ * type VariableProps = FcProps<VariableFC<'button', { notAlign?: boolean }>>;
+ * //   ^? {notAlign?: boolean} & Omit<ClassAttributes<HTMLButtonElement> & React.ButtonHTMLAttributes<HTMLButtonElement>, undefined>
+ */
+export type FCProps<Comp> = Comp extends FC<infer Props> ? Props : never;

package/src/types/react/FunctionalChildren.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+
+/**
+ * This type allows you to make children that can be function.
+ *
+ * @since 0.0.1
+ * @example
+ * type Child = FunctionalChildren<[options: string]>;
+ * // ReactNode | ((options: string) => ReactNode)
+ */
+export type FunctionalChildren<Args extends any[]> =
+  | ReactNode
+  | ((...args: Args) => ReactNode);

package/src/types/react/SetState.ts

@@ -0,0 +1,11 @@
+import type { Dispatch, SetStateAction } from 'react';
+
+/**
+ * Type of set state function from useState.
+ *
+ * @since 0.0.1
+ * @example
+ * // typeof setState => SetState<string>
+ * const [state, setState] = useState<string>('example');
+ */
+export type SetState<TType> = Dispatch<SetStateAction<TType>>;

package/src/types/react/VariableFC.ts

@@ -0,0 +1,48 @@
+import type { ComponentProps, ElementType, FC } from 'react';
+
+import type { AsyncFC, WeakOmit } from '@/types';
+
+/**
+ * This type wraps ComponentProps<A> to your FC.
+ *
+ * - __A__  - element type
+ * - __P__  - wrapping props
+ * - __Ex__ - excluded component props (for example, if you do not want to include 'children' prop in component)
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * type VariableComponentPropsWithChildren = ComponentProps<VariableFC<'div'>>;
+ * type VariableComponentPropsWithoutChildren = ComponentProps<VariableFC<'div', {}, 'children'>>;
+ *
+ * @example
+ * // With children
+ * const VariableComponent: VariableFC<'section', { variant?: 'default' }> = ({ variant, ...props }) => {
+ *   return <section {...props}></section>
+ * }
+ *
+ * @example
+ * // Without children
+ * const VariableComponent: VariableFC<'section', { variant?: 'default' }, 'children'> = ({ variant, ...props }) => {
+ *   return (
+ *    <section {...props}>
+ *      <div>Insert your own children</div>
+ *    </section>
+ *   );
+ * }
+ */
+export type VariableFC<
+  A extends ElementType,
+  P = unknown,
+  Ex extends keyof ComponentProps<A> | undefined = undefined,
+> = FC<P & WeakOmit<ComponentProps<A>, Ex>>;
+
+/**
+ * Works similar to {@link VariableFC}, but return type is Promise<ReactNode>;
+ * @since 0.0.1
+ */
+export type AsyncVariableFC<
+  A extends ElementType,
+  P = unknown,
+  Ex extends keyof ComponentProps<A> | undefined = undefined,
+> = AsyncFC<P & WeakOmit<ComponentProps<A>, Ex>>;

package/src/types/react/VariableProps.ts

@@ -0,0 +1,9 @@
+import type { ComponentProps, ElementType } from 'react';
+
+import type { FCProps, VariableFC } from '@/types';
+
+export type VariableProps<
+  A extends ElementType,
+  P = unknown,
+  Ex extends keyof ComponentProps<A> | undefined = undefined,
+> = FCProps<VariableFC<A, P, Ex>>;