@openzeppelin/ui-utils 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# @openzeppelin/ui-utils
+
+Shared, framework-agnostic utility functions for the OpenZeppelin UI ecosystem.
+
+[![npm version](https://img.shields.io/npm/v/@openzeppelin/ui-utils.svg)](https://www.npmjs.com/package/@openzeppelin/ui-utils)
+
+## Installation
+
+```bash
+# Using npm
+npm install @openzeppelin/ui-utils
+
+# Using yarn
+yarn add @openzeppelin/ui-utils
+
+# Using pnpm
+pnpm add @openzeppelin/ui-utils
+```
+
+## Purpose
+
+This package centralizes common logic that is not tied to any specific blockchain adapter or UI framework (like React). This prevents code duplication and ensures that core functionalities like logging, configuration management, and ID generation are consistent everywhere.
+
+## Key Exports
+
+- **`AppConfigService`**: A singleton service responsible for loading and providing runtime configuration. It can load settings from Vite environment variables or a `public/app.config.json` file, allowing for flexible configuration of RPC URLs, API keys, indexer endpoints, and other parameters.
+  - **RPC Endpoints**: Override default RPC URLs per network via `getRpcEndpointOverride(networkId)`.
+  - **Indexer Endpoints**: Override default indexer URLs per network via `getIndexerEndpointOverride(networkId)`.
+  - **API Keys**: Retrieve explorer API keys via `getExplorerApiKey(serviceId)`.
+  - **Global Services**: Access global service parameters like WalletConnect project IDs.
+  - **Feature Flags**: Check feature enablement via `isFeatureEnabled(flagName)`.
+
+- **`logger`**: A pre-configured singleton logger for consistent, leveled logging across all packages. It can be enabled, disabled, or have its level changed globally.
+
+- **`generateId`**: A utility for generating unique IDs, used for form fields and other components.
+
+- **`cn`**: A utility (a wrapper around `clsx` and `tailwind-merge`) for conditionally joining CSS class names, essential for building dynamic and themeable UI components with Tailwind CSS.
+
+- **Access Control Utilities** (`./src/access/`): Chain-agnostic utilities for access control operations:
+  - **`validateSnapshot`**: Validates the structure of an `AccessSnapshot` object
+  - **`serializeSnapshot`**: Serializes an access snapshot to JSON string
+  - **`deserializeSnapshot`**: Deserializes a JSON string to an access snapshot
+  - **`createEmptySnapshot`**: Creates an empty snapshot with no roles and no ownership
+  - **`findRoleAssignment`**: Finds a role assignment by role ID
+  - **`compareSnapshots`**: Compares two snapshots and returns differences
+  - **`isAccessControlError`**: Type guard to check if an error is an AccessControlError
+
+- **Address Normalization** (`normalizeAddress`, `addressesEqual`): Utilities for normalizing and comparing addresses in a chain-agnostic way.
+
+- **Type Guards and Helpers**: Various other small, reusable functions like `getDefaultValueForType`.
+
+## Package Structure
+
+```text
+utils/
+├── src/
+│   ├── access/                 # Access control utilities (snapshot, errors)
+│   ├── config/                 # Configuration management
+│   ├── logger/                 # Logging utilities
+│   ├── ui/                     # UI utility functions
+│   ├── validation/             # Validation and type utilities
+│   ├── constants/              # Shared constants
+│   └── index.ts                # Main package exports
+├── package.json
+├── tsconfig.json
+├── tsdown.config.ts
+├── vitest.config.ts
+└── README.md
+```
+
+## Usage
+
+```typescript
+import { AppConfigService, cn, generateId, logger } from '@openzeppelin/ui-utils';
+
+// Class name utility
+const buttonClasses = cn('px-4 py-2 rounded', isActive && 'bg-blue-500', disabled && 'opacity-50');
+
+// Logging
+logger.info('MyComponent', 'Component initialized');
+logger.error('MyComponent', 'An error occurred', error);
+
+// ID generation
+const fieldId = generateId('field_');
+
+// Configuration
+const appConfig = AppConfigService.getInstance();
+const rpcOverride = appConfig.getRpcEndpointOverride('ethereum-mainnet');
+```
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Run tests
+pnpm test
+
+# Lint
+pnpm lint
+```
+
+## License
+
+[AGPL-3.0](https://github.com/OpenZeppelin/openzeppelin-ui/blob/main/LICENSE)