@blockscout/ui-toolkit 0.0.1-alpha.2 → 0.0.1-alpha.4

package/README.md

@@ -1,28 +1,93 @@
-<!-- TODO @tom2drum rewrite README -->
-<!-- TODO @tom2drum add build check to CI workflow -->
-<!-- TODO @tom2drum add publish workflow -->
-<!-- TODO @tom2drum add eslint rules (?) to discourage use of IconSvg -->
-<!-- TODO @tom2drum tree shake project files (e.g config) -->
-<!-- TODO @tom2drum try to put all project deps to the toolkit folder -->
-<!-- TODO @tom2drum clean up tsconfig and vite config -->
+# Blockscout UI Toolkit
 
-# Your Organization's UI Toolkit
+A comprehensive collection of reusable Chakra UI components and theme system for Blockscout's projects. This toolkit provides a consistent design system and UI components to maintain visual consistency across Blockscout applications.
 
-A collection of reusable Chakra UI components and theme for your organization's projects.
+## Features
+
+- 🎨 Pre-configured Chakra UI theme with Blockscout's design system
+- 🧩 Reusable UI components built on Chakra UI
+- 🌓 Built-in dark mode support
+- 📱 Responsive and accessible components
+- 🔍 TypeScript support with proper type definitions
 
 ## Installation
 
+### Package Installation
+
+Install the package using your preferred package manager:
+
 ```bash
-npm install @your-org/toolkit
-# or
-yarn add @your-org/toolkit
+# Using npm
+npm install @blockscout/ui-toolkit
+
+# Using yarn
+yarn add @blockscout/ui-toolkit
+```
+
+### Required Dependencies
+
+Ensure you have the following peer dependencies installed:
+
+```json
+{
+  "dependencies": {
+    "@blockscout/ui-toolkit": "latest",
+    "@chakra-ui/react": ">=3.15.0",
+    "@emotion/react": ">=11.14.0",
+    "next": ">=15.2.3",
+    "next-themes": ">=0.4.4",
+    "react": ">=18.3.1",
+    "react-dom": ">=18.3.1",
+    "react-hook-form": ">=7.52.1"
+  },
+  "devDependencies": {
+    "@chakra-ui/cli": ">=3.15.0",
+    "@types/node": "^20",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
+    "typescript": "5.4.2"
+  }
+}
+```
+
+## Quick Start
+
+### 1. Theme Setup
+
+Create a `theme.ts` file in your project and configure the Blockscout theme:
+
+```tsx
+// Basic setup
+import { theme } from '@blockscout/ui-toolkit';
+export default theme;
+```
+
+Or extend the theme with custom overrides:
+
+```tsx
+import { createSystem } from '@chakra-ui/react';
+import { themeConfig } from '@blockscout/ui-toolkit';
+
+const customOverrides = {
+  // Add your custom theme overrides here
+  colors: {
+    brand: {
+      primary: '#your-color',
+    },
+  },
+};
+
+export default createSystem(themeConfig, customOverrides);
 ```
 
-## Usage
+### 2. Provider Setup
+
+Wrap your application with the ChakraProvider:
 
 ```tsx
-import { Button, theme } from '@your-org/toolkit';
 import { ChakraProvider } from '@chakra-ui/react';
+import { Button } from '@blockscout/ui-toolkit';
+import theme from './theme';
 
 function App() {
   return (
@@ -33,75 +98,73 @@ function App() {
 }
 ```
 
+### 3. TypeScript Support
+
+Add the following script to your `package.json` to generate Chakra UI type definitions:
+
+```json
+{
+  "scripts": {
+    "chakra:typegen": "chakra typegen ./src/theme.ts"
+  }
+}
+```
+
 ## Development
 
-1. Install dependencies:
+### Local Development
+
+1. Clone the repository and install dependencies:
 ```bash
-npm install
-# or
 yarn
 ```
 
-2. Start development server:
+2. Start the development server:
 ```bash
-npm run dev
-# or
 yarn dev
 ```
 
 3. Build the package:
 ```bash
-npm run build
-# or
 yarn build
 ```
 
-## Publishing
+### Publishing
+
+#### Manual Publishing
+
+1. Update the package version:
+```bash
+npm version <version-tag>
+```
 
-1. Update the version in `package.json`
 2. Build the package:
 ```bash
 npm run build
 ```
+
 3. Publish to NPM:
 ```bash
-npm publish
+npm publish --access public
 ```
 
-## Available Components
-
-- Accordion
-- Alert
-- Avatar
-- Badge
-- Button
-- Checkbox
-- Close Button
-- Collapsible
-- Color Mode
-- Dialog
-- Drawer
-- Field
-- Heading
-- Icon Button
-- Image
-- Input
-- Input Group
-- Link
-- Menu
-- Pin Input
-- Popover
-- Progress Circle
-- Provider
-- Radio
-- Rating
-- Select
-- Skeleton
-- Slider
-- Switch
-- Table
-- Tabs
-- Tag
-- Textarea
-- Toaster
-- Tooltip 
+#### Automated Publishing
+
+Use the `toolkit-npm-publisher.yml` GitHub Actions workflow for automated publishing.
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Support
+
+For issues, feature requests, or questions, please open an issue in the repository.
+
+## License
+
+This project is licensed under the GNU General Public License v3.

package/dist/chakra/select.d.ts

@@ -17,7 +17,10 @@ interface SelectContentProps extends ChakraSelect.ContentProps {
     portalRef?: React.RefObject<HTMLElement>;
 }
 export declare const SelectContent: React.ForwardRefExoticComponent<SelectContentProps & React.RefAttributes<HTMLDivElement>>;
-export declare const SelectItem: React.ForwardRefExoticComponent<ChakraSelect.ItemProps & React.RefAttributes<HTMLDivElement>>;
+export interface SelectItemProps extends ChakraSelect.ItemProps {
+    item: SelectOption;
+}
+export declare const SelectItem: React.ForwardRefExoticComponent<SelectItemProps & React.RefAttributes<HTMLDivElement>>;
 interface SelectValueTextProps extends Omit<ChakraSelect.ValueTextProps, 'children'> {
     children?(items: Array<SelectOption>): React.ReactNode;
     size?: SelectRootProps['size'];

package/dist/components/AdaptiveTabs/index.d.ts

@@ -0,0 +1,3 @@
+export type { TabItemRegular, TabItemMenu, SubTabItem } from './types';
+export type { Props } from './AdaptiveTabs';
+export { default } from './AdaptiveTabs';

package/dist/components/Hint/Hint.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { IconButtonProps } from '../../chakra/icon-button';
+import { TooltipProps } from '../../chakra/tooltip';
+interface Props extends IconButtonProps {
+    label: string | React.ReactNode;
+    tooltipProps?: Partial<TooltipProps>;
+    isLoading?: boolean;
+    as?: React.ElementType;
+}
+export declare const Hint: React.MemoExoticComponent<({ label, tooltipProps, isLoading, ...rest }: Props) => React.JSX.Element>;
+export {};

package/dist/components/RoutedTabs/index.d.ts

@@ -0,0 +1,3 @@
+export { default as RoutedTabs } from './RoutedTabs';
+export { default as RoutedTabsSkeleton } from './RoutedTabsSkeleton';
+export { default as useActiveTabFromQuery } from './useActiveTabFromQuery';

package/dist/components/buttons/BackToButton.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+import { IconButtonProps } from '../../chakra/icon-button';
+export interface BackToButtonProps extends IconButtonProps {
+    href?: string;
+    hint?: string;
+}
+export declare const BackToButton: ({ href, hint, ...rest }: BackToButtonProps) => React.JSX.Element;

package/dist/components/buttons/ClearButton.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+import { CloseButtonProps } from '../../chakra/close-button';
+export interface ClearButtonProps extends CloseButtonProps {
+    visible?: boolean;
+}
+export declare const ClearButton: ({ disabled, visible, ...rest }: ClearButtonProps) => React.JSX.Element;

package/dist/components/{Filter → filters}/FilterInput.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { InputProps } from '../../chakra/input';
 import { SkeletonProps } from '../../chakra/skeleton';
-interface Props extends Omit<SkeletonProps, 'onChange' | 'loading'> {
+export interface FilterInputProps extends Omit<SkeletonProps, 'onChange' | 'loading'> {
     onChange?: (searchTerm: string) => void;
     onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
     onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
@@ -13,5 +13,4 @@ interface Props extends Omit<SkeletonProps, 'onChange' | 'loading'> {
     name?: string;
     inputProps?: InputProps;
 }
-declare const FilterInput: ({ onChange, size, placeholder, initialValue, type, name, loading, onFocus, onBlur, inputProps, ...rest }: Props) => React.JSX.Element;
-export default FilterInput;
+export declare const FilterInput: ({ onChange, size, placeholder, initialValue, type, name, loading, onFocus, onBlur, inputProps, ...rest }: FilterInputProps) => React.JSX.Element;

package/dist/components/forms/components/FormFieldError.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+interface Props {
+    message: string;
+    className?: string;
+}
+export declare const FormFieldError: import('@chakra-ui/react').ChakraComponent<({ message, className }: Props) => React.JSX.Element, {}>;
+export {};

package/dist/components/forms/components/index.d.ts

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

package/dist/components/forms/fields/FormFieldAddress.d.ts

@@ -0,0 +1,5 @@
+import { default as React } from 'react';
+import { FieldValues } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+import { PartialBy } from '../../../../types/utils';
+export declare const FormFieldAddress: <FormFields extends FieldValues>(props: PartialBy<FormFieldPropsBase<FormFields>, 'placeholder'>) => React.JSX.Element;

package/dist/components/forms/fields/FormFieldCheckbox.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { FieldValues, Path } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+import { CheckboxProps } from '../../../chakra/checkbox';
+interface Props<FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>> extends Pick<FormFieldPropsBase<FormFields, Name>, 'rules' | 'name' | 'onChange' | 'readOnly'>, Omit<CheckboxProps, 'name' | 'onChange'> {
+    label: string;
+}
+export declare const FormFieldCheckbox: <FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>>({ name, label, rules, onChange, readOnly, ...rest }: Props<FormFields, Name>) => React.JSX.Element;
+export {};

package/dist/components/forms/fields/FormFieldColor.d.ts

@@ -0,0 +1,9 @@
+import { BoxProps } from '@chakra-ui/react';
+import { default as React } from 'react';
+import { FieldValues, Path } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+interface Props<FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>> extends FormFieldPropsBase<FormFields, Name> {
+    sampleDefaultBgColor?: BoxProps['bgColor'];
+}
+export declare const FormFieldColor: <FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>>({ name, placeholder, rules, onBlur, group, inputProps, size, disabled, sampleDefaultBgColor, ...restProps }: Props<FormFields, Name>) => React.JSX.Element;
+export {};

package/dist/components/forms/fields/FormFieldEmail.d.ts

@@ -0,0 +1,5 @@
+import { default as React } from 'react';
+import { FieldValues } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+import { PartialBy } from '../../../../types/utils';
+export declare const FormFieldEmail: <FormFields extends FieldValues>(props: PartialBy<FormFieldPropsBase<FormFields>, 'placeholder'>) => React.JSX.Element;

package/dist/components/forms/fields/FormFieldSelect.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+import { Path, FieldValues } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+import { SelectProps } from '../../../chakra/select';
+type Props<FormFields extends FieldValues, Name extends Path<FormFields>> = FormFieldPropsBase<FormFields, Name> & SelectProps;
+export declare const FormFieldSelect: <FormFields extends FieldValues, Name extends Path<FormFields>>(props: Props<FormFields, Name>) => React.JSX.Element;
+export {};

package/dist/components/forms/fields/FormFieldSelectAsync.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+import { Path, FieldValues } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+import { SelectAsyncProps } from '../../../chakra/select';
+type Props<FormFields extends FieldValues, Name extends Path<FormFields>> = FormFieldPropsBase<FormFields, Name> & SelectAsyncProps;
+export declare const FormFieldSelectAsync: <FormFields extends FieldValues, Name extends Path<FormFields>>(props: Props<FormFields, Name>) => React.JSX.Element;
+export {};

package/dist/components/forms/fields/FormFieldText.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { FieldValues, Path } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+interface Props<FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>> extends FormFieldPropsBase<FormFields, Name> {
+    asComponent?: 'Input' | 'Textarea';
+}
+export declare const FormFieldText: <FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>>({ name, placeholder, rules, onBlur, group, inputProps, asComponent, size: sizeProp, disabled, floating: floatingProp, ...restProps }: Props<FormFields, Name>) => React.JSX.Element;
+export {};

package/dist/components/forms/fields/FormFieldUrl.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldValues } from 'react-hook-form';
+import { FormFieldPropsBase } from './types';
+export declare const FormFieldUrl: <FormFields extends FieldValues>(props: FormFieldPropsBase<FormFields>) => React.JSX.Element;

package/dist/components/forms/fields/image/FormFieldImagePreview.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { ColorMode } from '../../../../chakra/color-mode';
+interface Props {
+    src: string | undefined;
+    onLoad?: () => void;
+    onError?: () => void;
+    isInvalid: boolean;
+    className?: string;
+    fallback: React.ReactElement;
+    colorMode?: ColorMode;
+}
+export declare const FormFieldImagePreview: import('@chakra-ui/react').ChakraComponent<React.MemoExoticComponent<({ src, isInvalid, onError, onLoad, className, fallback: fallbackProp, colorMode, }: Props) => React.JSX.Element>, {}>;
+export {};

package/dist/components/forms/fields/image/useImageField.d.ts

@@ -0,0 +1,25 @@
+import { FieldValues, Path } from 'react-hook-form';
+interface Params<FormFields extends FieldValues, Name extends Path<FormFields>> {
+    name: Name;
+    isRequired?: boolean;
+}
+interface ReturnType {
+    input: {
+        rules: {
+            required?: boolean;
+            validate: {
+                preview: () => string | true;
+            };
+        };
+        isRequired?: boolean;
+        onBlur: () => void;
+    };
+    preview: {
+        src: string | undefined;
+        isInvalid: boolean;
+        onLoad: () => void;
+        onError: () => void;
+    };
+}
+export declare function useImageField<FormFields extends FieldValues, Name extends Path<FormFields>>({ name, isRequired, }: Params<FormFields, Name>): ReturnType;
+export {};

package/dist/components/forms/fields/index.d.ts

@@ -0,0 +1,10 @@
+export * from './image/FormFieldImagePreview';
+export * from './image/useImageField';
+export * from './FormFieldAddress';
+export * from './FormFieldCheckbox';
+export * from './FormFieldColor';
+export * from './FormFieldEmail';
+export * from './FormFieldSelect';
+export * from './FormFieldSelectAsync';
+export * from './FormFieldText';
+export * from './FormFieldUrl';

package/dist/components/forms/fields/types.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { ControllerRenderProps, FieldValues, Path, RegisterOptions } from 'react-hook-form';
+import { FieldProps } from '../../../chakra/field';
+import { InputProps } from '../../../chakra/input';
+import { InputGroupProps } from '../../../chakra/input-group';
+import { TextareaProps } from '../../../chakra/textarea';
+export interface FormFieldPropsBase<FormFields extends FieldValues, Name extends Path<FormFields> = Path<FormFields>> extends Omit<FieldProps, 'children'> {
+    name: Name;
+    placeholder: string;
+    rules?: Omit<RegisterOptions<FormFields, Name>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
+    onBlur?: () => void;
+    onChange?: () => void;
+    inputProps?: InputProps | TextareaProps;
+    group?: Omit<InputGroupProps, 'children' | 'endElement'> & {
+        endElement?: React.ReactNode | (({ field }: {
+            field: ControllerRenderProps<FormFields, Name>;
+        }) => React.ReactNode);
+    };
+}

package/dist/components/forms/inputs/file/DragAndDropArea.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+interface Props {
+    children: React.ReactNode;
+    onDrop: (files: Array<File>) => void;
+    className?: string;
+    isDisabled?: boolean;
+    isInvalid?: boolean;
+    fullFilePath?: boolean;
+}
+export declare const DragAndDropArea: import('@chakra-ui/react').ChakraComponent<({ onDrop, children, className, isDisabled, fullFilePath, isInvalid }: Props) => React.JSX.Element, {}>;
+export {};

package/dist/components/forms/inputs/file/FileInput.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { ControllerRenderProps, FieldValues, Path } from 'react-hook-form';
+interface InjectedProps {
+    onChange: (files: Array<File>) => void;
+}
+interface Props<V extends FieldValues, N extends Path<V>> {
+    children: React.ReactNode | ((props: InjectedProps) => React.ReactNode);
+    field: ControllerRenderProps<V, N>;
+    accept?: string;
+    multiple?: boolean;
+}
+export declare const FileInput: <Values extends FieldValues, Names extends Path<Values>>({ children, accept, multiple, field }: Props<Values, Names>) => React.JSX.Element;
+export {};

package/dist/components/forms/inputs/file/FileSnippet.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+interface Props {
+    file: File;
+    className?: string;
+    index?: number;
+    onRemove?: (index?: number) => void;
+    isDisabled?: boolean;
+    error?: string;
+}
+export declare const FileSnippet: import('@chakra-ui/react').ChakraComponent<({ file, className, index, onRemove, isDisabled, error }: Props) => React.JSX.Element, {}>;
+export {};

package/dist/components/forms/inputs/file/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function getAllFileEntries(dataTransferItemList: DataTransferItemList): Promise<Array<FileSystemFileEntry>>;
+export declare function convertFileEntryToFile(entry: FileSystemFileEntry, fullFilePath?: boolean): Promise<File>;

package/dist/components/forms/inputs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './file/DragAndDropArea';
+export * from './file/FileInput';
+export * from './file/FileSnippet';

package/dist/components/forms/utils/getFormFieldErrorText.d.ts

@@ -0,0 +1,2 @@
+import { FieldError } from 'react-hook-form';
+export declare function getFormFieldErrorText(error: FieldError | undefined): string | undefined;

package/dist/components/forms/utils/index.d.ts

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

package/dist/components/forms/validators/address.d.ts

@@ -0,0 +1,3 @@
+export declare const ADDRESS_REGEXP: RegExp;
+export declare const ADDRESS_LENGTH = 42;
+export declare function addressValidator(value: string | undefined): true | "Incorrect address format";

package/dist/components/forms/validators/color.d.ts

@@ -0,0 +1,2 @@
+export declare const COLOR_HEX_REGEXP: RegExp;
+export declare const colorValidator: (value: unknown) => true | "Invalid length" | "Invalid hex code";

package/dist/components/forms/validators/email.d.ts

@@ -0,0 +1,2 @@
+export declare const EMAIL_REGEXP: RegExp;
+export declare const emailValidator: (value: string) => true | "Invalid email";

package/dist/components/forms/validators/index.d.ts

@@ -0,0 +1,7 @@
+export * from './address';
+export * from './color';
+export * from './email';
+export * from './signature';
+export * from './text';
+export * from './transaction';
+export * from './url';

package/dist/components/forms/validators/signature.d.ts

@@ -0,0 +1 @@
+export declare const SIGNATURE_REGEXP: RegExp;

package/dist/components/forms/validators/text.d.ts

@@ -0,0 +1 @@
+export declare const noWhitespaceValidator: (value: unknown) => true | "Should contain text";

package/dist/components/forms/validators/transaction.d.ts

@@ -0,0 +1,2 @@
+export declare const TRANSACTION_HASH_REGEXP: RegExp;
+export declare const TRANSACTION_HASH_LENGTH = 66;

package/dist/components/forms/validators/url.d.ts

@@ -0,0 +1,3 @@
+export declare function urlValidator(value: string | undefined): true | "Incorrect URL";
+export declare const DOMAIN_REGEXP: RegExp;
+export declare function domainValidator(value: string | undefined): true | "Incorrect domain";

package/dist/components/truncation/TruncatedTextTooltip.d.ts

@@ -0,0 +1,8 @@
+import { Placement } from '@floating-ui/dom';
+import { default as React } from 'react';
+export interface TruncatedTextTooltipProps {
+    children: React.ReactNode;
+    label: React.ReactNode;
+    placement?: Placement;
+}
+export declare const TruncatedTextTooltip: React.MemoExoticComponent<({ children, label, placement }: TruncatedTextTooltipProps) => React.JSX.Element>;

package/dist/hooks/useClipboard.d.ts

@@ -1,4 +1,4 @@
-export default function useClipboard(text: string, timeout?: number): {
+export declare function useClipboard(text: string, timeout?: number): {
     hasCopied: boolean;
     copy: () => void;
     disclosure: {

package/dist/hooks/useFirstMountState.d.ts

@@ -0,0 +1 @@
+export declare function useFirstMountState(): boolean;

package/dist/hooks/useIsSticky.d.ts

@@ -0,0 +1,2 @@
+import { default as React } from 'react';
+export declare function useIsSticky(ref: React.RefObject<HTMLDivElement>, offset?: number, isEnabled?: boolean): boolean;

package/dist/hooks/useUpdateEffect.d.ts

@@ -0,0 +1,2 @@
+import { default as React } from 'react';
+export declare const useUpdateEffect: typeof React.useEffect;

package/dist/hooks/useViewportSize.d.ts

@@ -1,4 +1,4 @@
-export default function useViewportSize(debounceTime?: number): {
+export declare function useViewportSize(debounceTime?: number): {
     width: number;
     height: number;
 };