elseware-ui
v4.3.0
Published
A modern and customizable React UI component library by elseware Technology.
Readme
elseware-ui
A TypeScript-first React component library for browser applications. It provides reusable components and compositions styled with Tailwind CSS.
Features
- React 18 and 19 support
- Tailwind CSS design tokens and a reusable preset
- Tree-shakable ESM build for browsers
- Storybook 10 component development and production builds
- TypeScript 7 validation
- Oxlint, Prettier, Knip, lint-staged, and Husky quality gates
Installation
Install the library and its peer dependencies.
npm install elseware-ui react react-dom formik yup tailwindcssImport the browser API and compiled styles:
import { Button } from "elseware-ui";
import "elseware-ui/styles.css";Package exports
The package exposes its browser JavaScript, declarations, CSS, and Tailwind preset:
{
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"default": "./dist/index.mjs"
},
"./tailwind": "./tailwind.preset.js",
"./styles.css": "./dist/index.css"
}Upgrading to 4.0
This major release supports browsers only. Remove imports of
elseware-ui/native and any React Native or NativeWind setup used solely by
Elseware UI. Buttons now use onClick, aria-label, role, and data-testid
instead of onPress, accessibilityLabel, accessibilityRole, and testID.
File inputs accept File | null; the unused onFileSelect callback and native
file value type have been removed.
Tailwind preset
Add the package preset and include the distributed component sources or compiled application usage in your Tailwind content configuration as appropriate for your application:
const elsewarePreset = require("elseware-ui/tailwind");
module.exports = {
presets: [elsewarePreset],
content: ["./src/**/*.{js,jsx,ts,tsx}"],
};The preset reads its color scales from src/data/palette.json. Components and
compositions use eui-* color utilities; CSS and SVG colors use matching
--eui-color-<name>-<shade> variables emitted by the preset. To customize a
published package, override both the Tailwind color scale and those variables
after importing elseware-ui/styles.css. Include
node_modules/elseware-ui/dist/index.mjs in Tailwind's content paths so its
component utilities are regenerated with the application palette.
Development
npm install
npm run devThe main quality commands are:
npm run typecheck # Type-check library and Storybook
npm run lint # Run Oxlint with warnings denied
npm run format:check # Verify Prettier formatting
npm run deadcode # Check files and dependency reachability
npm run build # Build JS, CSS, and TS7 declarations
npm run build:storybook # Build the production Storybook
npm run validate # Run the complete quality pipelinenpm install initializes Husky for repository contributors. The pre-commit hook runs lint-staged; it can also be invoked directly with npm run precommit.
Component structure
Shared behavior and types can live in base modules. Each browser renderer lives
in its component folder and is exported by the local index.ts. Use DOM event,
accessibility, and file types in public props.
Web component styles stay beside their owning component and are imported by that component's implementation or local barrel. Do not register component styles in a root CSS manifest. The build follows the web module graph and extracts those imports into the public elseware-ui/styles.css bundle. Only design-system-wide foundations belong in src/styles.
Use type-only imports for TypeScript types and keep imports grouped as external, internal, data, and types where those groups are useful.
Source naming and export rules are documented in docs/Architecture.md. Leaf barrels use explicit runtime exports and export type; aggregate barrels use direct wildcard exports for their immediate child boundaries. Implementation code must not import explicit index files.
Publishing
Pull requests targeting main run the complete validation suite and verify
that the package version has not already been published. A successful merge to
main runs the same checks and publishes through GitHub's OIDC trusted
publishing; no long-lived npm token is stored in GitHub. Because this source
repository is private, the workflow disables npm provenance, which npm only
accepts for public source repositories.
Before enabling the workflow, configure npm's trusted publisher for the
elseware-ui package with the GitHub organization/repository and the workflow
filename .github/workflows/publish.yml. Create the npm-production GitHub
environment and restrict it to the main branch. Keep the package version in
package.json and package-lock.json synchronized; bump it in the release PR:
npm version patch --no-git-tag-versionThe workflow deliberately fails before publishing if that exact version is
already present in the npm registry. If this repository is later made public,
remove --provenance=false from the publish workflow to enable signed npm
provenance attestations.
For a local release preview, use:
npm run validate
npm publish --dry-run --access public --provenance=false --ignore-scriptsThe release command runs the full validation pipeline before publishing publicly.
