elseware-ui 2.35.0 → 2.36.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 elseware Technology
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 elseware Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,53 +1,91 @@
 # elseware-ui
 
-A modern React component library for building web and desktop user interfaces.
+A modern, customizable React component library for building web and desktop user interfaces.
 
-`elseware-ui` provides a collection of reusable, customizable, and production-ready UI components designed to accelerate application development while maintaining consistency, accessibility, and scalability.
+`elseware-ui` provides reusable, production-ready UI components designed to speed up application development while maintaining consistency, accessibility, scalability, and a clean developer experience.
 
 ## Features
 
-- TypeScript-first development
+- TypeScript-first component development
 - React-based component architecture
 - Tailwind CSS integration
-- Customizable themes and styling
-- Consistent design system
+- Customizable themes, variants, shapes, and styles
+- Shared design tokens, enums, animations, and SVG utilities
+- Modular barrel exports
+- Tree-shakable ESM build
+- Storybook-powered component development
+- Linting, formatting, type checking, and build validation
 - Web and desktop application support
-- Storybook-powered component documentation
-- Modular and tree-shakable components
 - Developer-friendly APIs
 
+## Installation
+
+Install the package:
+
+```bash
+npm install elseware-ui
+```
+
+Install required peer dependencies if they are not already installed:
+
+```bash
+npm install react react-dom tailwindcss
+```
+
+## Package Exports
+
+The package exposes the main component API and compiled styles:
+
+```json
+{
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.js",
+    "require": "./dist/index.cjs"
+  },
+  "./styles.css": "./dist/index.css"
+}
+```
+
+Recommended usage:
+
+```tsx
+import { Button } from "elseware-ui";
+import "elseware-ui/styles.css";
+```
+
 ## Component Import Structure
 
-Use the following import ordering convention when creating components:
+Use the following import ordering convention when creating or updating components:
 
 ```ts
 // External
 
 // Internal
 
-// Types
-
 // Data
+
+// Types
 ```
 
 Example:
 
 ```ts
 // External
-import { ReactNode } from "react";
+import React from "react";
 
 // Internal
-import { cn } from "@/utils";
-
-// Types
-import { BaseComponentProps } from "@/interfaces";
-import { Variant, Shape, Size } from "@/types";
+import { cn } from "../../../utils";
 
 // Data
-import { shapes, variants, borderVariants, avatarSizes } from "@/data/styles";
+import { Shape, Variant } from "../../../data/enums";
+import { shapes, variants } from "../../../data/styles";
+
+// Types
+import type { BaseComponentProps } from "../../../interfaces";
 ```
 
-## Installation
+## Development
 
 Install dependencies:
 
@@ -55,34 +93,181 @@ Install dependencies:
 npm install
 ```
 
-## Development
-
-Start Storybook for component development and testing:
+Start Storybook:
 
 ```bash
 npm run dev
 ```
 
-## Build
-
 Build the component library:
 
 ```bash
 npm run build
 ```
 
+Build Storybook:
+
+```bash
+npm run build:storybook
+```
+
+## Code Quality
+
+Run TypeScript checks:
+
+```bash
+npm run typecheck
+```
+
+Run ESLint:
+
+```bash
+npm run lint
+```
+
+Fix lint issues:
+
+```bash
+npm run lint:fix
+```
+
+Format files with Prettier:
+
+```bash
+npm run format
+```
+
+Check formatting:
+
+```bash
+npm run format:check
+```
+
+Check unused files, exports, and dependencies:
+
+```bash
+npm run deadcode
+```
+
+Run the full validation pipeline:
+
+```bash
+npm run validate
+```
+
+Run automatic lint fixes, formatting, and validation:
+
+```bash
+npm run full
+```
+
+## Git Hooks
+
+Initialize Husky:
+
+```bash
+npm run prepare:husky
+```
+
+Recommended pre-commit hook:
+
+```bash
+npx lint-staged
+```
+
 ## Publishing
 
-Publish a new package version to npm:
+Before publishing, update the package version:
+
+```bash
+npm version patch
+```
+
+or:
+
+```bash
+npm version minor
+```
+
+or:
+
+```bash
+npm version major
+```
+
+Then publish:
 
 ```bash
 npm run release
 ```
 
+The `release` script validates the package before publishing.
+
+## Component Guidelines
+
+When building components:
+
+- Keep components modular and focused
+- Move reusable enums to `src/data/enums.ts`
+- Move reusable style maps to `src/data/styles.tsx`
+- Move reusable animation class maps to `src/data/animations.tsx`
+- Move generic SVG icons to `src/data/svgs.tsx`
+- Keep component-specific state logic in hooks when possible
+- Keep public types in each component's `types.ts`
+- Export each component through its local `index.ts`
+- Avoid unnecessary dependencies between unrelated component groups
+
+## Barrel Export Pattern
+
+Each component should expose a local barrel file:
+
+```ts
+export * from "./Button";
+export * from "./types";
+```
+
+Component groups should also expose barrel exports:
+
+```ts
+export * from "./avatar";
+export * from "./badge";
+export * from "./toast";
+```
+
+The root entry point should expose the public package API:
+
+```ts
+export * from "./components";
+export * from "./compositions";
+export * from "./hooks";
+export * from "./layouts";
+export * from "./providers";
+export * from "./routing";
+export * from "./utils";
+export * from "./interfaces";
+export * from "./types";
+```
+
+## Styling
+
+`elseware-ui` uses Tailwind CSS and shared design tokens.
+
+Consumers should import the compiled stylesheet once in their application entry:
+
+```tsx
+import "elseware-ui/styles.css";
+```
+
 ## Documentation
 
 Interactive component documentation and examples are available through Storybook.
 
+Start Storybook locally:
+
+```bash
+npm run dev
+```
+
 ## About elseware Technology
 
 elseware Technology builds tools, frameworks, and solutions for software engineering, cloud computing, game development, and developer productivity.
@@ -91,6 +276,12 @@ elseware Technology builds tools, frameworks, and solutions for software enginee
 
 Contributions, issues, and feature requests are welcome.
 
+Before opening a pull request, run:
+
+```bash
+npm run validate
+```
+
 ## License
 
 This project is licensed under the MIT License.