@banzamel/mineralui 0.2.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafał Polak
+
+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,6 +1,12 @@
 # MineralUI
 
-Modern React UI component library with a unique **mineral dark aesthetic** — glassmorphism effects, cyan accents, and dark backgrounds. Zero runtime dependencies.
+React component framework for dashboards, admin panels, documentation shells, settings screens and data-heavy internal products.
+
+- npm: `@banzamel/mineralui`
+- release version: `0.4.0`
+- peer dependencies: `react >= 18`, `react-dom >= 18`
+- repository: `https://github.com/Banzamel/mineralui`
+- styles: plain `.css` files + CSS variables exposed as `--mineral-*`
 
 ## Installation
 
@@ -8,107 +14,179 @@ Modern React UI component library with a unique **mineral dark aesthetic** — g
 npm install @banzamel/mineralui
 ```
 
+```tsx
+import '@banzamel/mineralui/styles.css'
+```
+
 ## Quick Start
 
 ```tsx
-import {MineralThemeProvider, Input, Select, DatePicker} from '@banzamel/mineralui';
-import '@banzamel/mineralui/styles.css';
-
-function App() {
+import {
+    MThemeProvider,
+    MButton,
+    MCard,
+    MCardBody,
+    MCardHeader,
+    MInput,
+    MSelect,
+    MStack,
+} from '@banzamel/mineralui'
+import '@banzamel/mineralui/styles.css'
+
+function AccountSettings() {
     return (
-        <MineralThemeProvider>
-            <Input label="Name" variant="outlined" />
-            <Select
-                label="Country"
-                options={[
-                    {value: 'pl', label: 'Poland'},
-                    {value: 'de', label: 'Germany'},
-                ]}
-            />
-            <DatePicker label="Birth date" locale="pl" />
-        </MineralThemeProvider>
-    );
+        <MThemeProvider mode="dark">
+            <MCard>
+                <MCardHeader title="Workspace settings" description="Basic account data and role assignment." />
+                <MCardBody>
+                    <MStack gap="md">
+                        <MInput label="Workspace name" placeholder="Banzamel Studio" fullWidth />
+                        <MSelect
+                            label="Default role"
+                            fullWidth
+                            options={[
+                                {value: 'owner', label: 'Owner'},
+                                {value: 'editor', label: 'Editor'},
+                            ]}
+                        />
+                        <MButton>Save changes</MButton>
+                    </MStack>
+                </MCardBody>
+            </MCard>
+        </MThemeProvider>
+    )
 }
 ```
 
-## Components
+## What Is Included
 
-### Inputs
-| Component | Description |
-|-----------|-------------|
-| `Input` | Base input — variants, sizes, colors, icons, loading, clearable |
-| `Textarea` | Multiline with autoResize, minRows/maxRows |
-| `InputPassword` | Show/hide toggle, strength indicator |
-| `InputNumber` | Stepper buttons, min/max/step, long-press |
-| `InputSearch` | Debounced search with instant Enter |
-| `InputEmail` | RFC email validation |
-| `InputPhone` | Country code prefix, digit formatting |
-| `InputName` | Auto-capitalize, strip special chars |
-| `InputIBAN` | MOD-97 checksum, country-aware formatting |
-| `InputTaxId` | NIP/PESEL/REGON with weighted checksum |
-| `InputCurrency` | Symbol, thousand separators, precision |
+### Theme and primitives
+- `MThemeProvider`, `useMTheme`
+- `MPortal`, `MPopover`
+- CSS variable token system for dark and light mode
+- scoped theme overrides through the provider
+
+### Layout
+- `MContainer`, `MSection`
+- `MStack`, `MInline`, `MGrid`, `MGridItem`
+- `MSurface`, `MDivider`
+- `MHeader`, `MFooter`, `MNavbar`, `MNavs`, `MTabs`
+
+### Display
+- `MCard`, `MCardHeader`, `MCardBody`, `MCardFooter`
+- `MBadge`, `MAlert`
+- `MTable`, `MTableRoot`, `MTableHead`, `MTableBody`, `MTableRow`, `MTableHeadCell`, `MTableCell`
+- `MCollapsible`, `MSpinner`, `MLoader`
+- `MAvatar`, `MModal`
+- `MCalendarBoard`, `MCalendarDayCell`, `MCalendarEventList`, `MCalendarEventItem`, `MCalendarEventPopover`, `MCalendarTimeline`
+
+### Typography
+- `MHeading`, `MText`, `MLink`, `MCode`, `MList`, `MListItem`
 
 ### Controls
-| Component | Description |
-|-----------|-------------|
-| `Checkbox` | Custom visual, indeterminate state, colors |
-| `Radio` / `RadioGroup` | Context-based group, arrow key navigation |
-| `Toggle` | Switch on/off with sliding knob |
+- `MButton`
+- `MCheckbox`
+- `MRadio`, `MRadioGroup`
+- `MToggle`
+
+### Inputs
+- `MInput`, `MTextarea`
+- `MInputPassword`, `MInputNumber`, `MInputSearch`, `MInputEmail`
+- `MInputPhone`, `MInputName`, `MInputIBAN`, `MInputTaxId`, `MInputCurrency`
+- `MInputCreditCard`, `MInputPostCode`
+- `MInputGroup`
 
 ### Dropdowns
-| Component | Description |
-|-----------|-------------|
-| `Select` | Single/multi (chips), searchable, grouped, keyboard nav |
-| `Autocomplete` | Generic\<T\>, freeSolo, async loading, multiple tags |
-| `DatePicker` | Calendar grid, month/year nav, min/max, locale pl/en |
-| `TimePicker` | Scrollable columns, minuteStep, 12h/24h format |
+- `MSelect`
+- `MAutocomplete`
+- `MDatePicker`
+- `MDateRangePicker`
+- `MTimePicker`
 
-### Form
-| Component | Description |
-|-----------|-------------|
-| `Form` | FormContext provider, validation modes, submit handling |
-| `useFormField` | Hook for field registration and validation |
+### Form and validation
+- `MForm`, `useFormField`, `useFormContext`
+- validators: `validateEmail`, `validatePhone`, `validateIBAN`, `validateNIP`, `validatePESEL`, `validateREGON`
+- formatters: `formatIBAN`, `formatPhone`, `formatNIP`, `formatCurrency`, `parseCurrencyToNumber`
+- date helpers: `formatDate`, `parseDate`, `formatTime`, `parseTime`
 
-### Primitives
-`Portal`, `Popover` (auto-flip positioning, glassmorphism)
+### Hooks and utilities
+- `mergeClasses`
+- `useDebounce`, `useDebouncedCallback`
+- `useOutsideClick`
+- `useKeyNavigation`
+- `useClickEffect`
 
-## Theming
+## Design System Notes
 
-MineralUI uses CSS Custom Properties for full customization:
+MineralUI is driven by CSS variables and readable class names.
 
 ```css
 :root {
-    --mineral-primary: #00A5DE;
-    --mineral-dark: #0f172a;
-    --mineral-surface: #1a1a2e;
-    --mineral-text: #e2e8f0;
+    --mineral-primary-rgb: 0, 165, 222;
+    --mineral-primary: rgba(0, 165, 222, 1);
+    --mineral-surface: rgba(255, 255, 255, 1);
+    --mineral-text: rgba(17, 24, 39, 1);
+    --mineral-border: rgba(203, 213, 225, 1);
 }
 ```
 
-**4 levels of customization:** CSS Variables → Props → className → ThemeProvider
+You can theme the package in four layers:
+- token overrides through `--mineral-*`
+- component props such as `color`, `fcolor`, `spacing`, `padding`, `fsize`
+- `className` for local integration
+- `MThemeProvider` for `mode` and scoped token overrides
 
-## Built-in Utilities
+Framework defaults:
+- plain CSS, not CSS Modules
+- readable local class names
+- no runtime dependencies besides React peer dependencies
+- dark and light mode supported through the same token system
+- default scrollbar styling and typography reset come from the framework styles
 
-```tsx
-// Validators (zero dependencies)
-import {validateIBAN, validateNIP, validatePESEL, validateEmail} from '@banzamel/mineralui';
+## Feature Highlights
+
+### Layout-first API
+- `MStack`, `MInline` and `MGrid` cover the majority of internal dashboard layouts without extra utility libraries.
+- `MGrid` supports equal columns by default and responsive span overrides with `sm`, `md`, `lg`, `xl`.
+
+### Form-heavy components
+- Specialized inputs handle formatting and validation instead of pushing that logic into every application.
+- `MInputCreditCard` detects brand and keeps formatting readable.
+- `MInputPostCode` validates against country-specific postal code rules.
 
-// Formatters
-import {formatIBAN, formatCurrency, formatPhone} from '@banzamel/mineralui';
+### Date workflows
+- `MDatePicker` and `MDateRangePicker` support inline and popover usage.
+- `MDateRangePicker` ships with built-in presets such as `Today`, `Last 7 days`, `Last 30 days`, `This month`, and `Previous month`.
+- `MCalendarBoard` covers non-form calendar surfaces such as planning, invoices, birthdays, and task density views.
 
-// Hooks
-import {useDebounce, useClickOutside, useKeyboardNav} from '@banzamel/mineralui';
+### Interaction model
+- Buttons, cards, avatars, tabs and interactive inputs can share the same click effect model.
+- Navigation and picker overlays render through shared popover primitives.
+
+## Build and Checks
+
+```bash
+npm run format
+npm run format:check
+npm run build
 ```
 
-## Key Features
+Known note:
+- `vite-plugin-dts` / API Extractor currently warns about its bundled TypeScript version versus the installed project version, but the build completes successfully.
+
+## Local Verification Surface
+
+The working documentation and preview site lives in the sibling project:
+
+- `../mineralui-website`
+
+That site is wired to the local package build through `file:../mineralui` and is the primary visual verification surface before release.
+
+## Repository
 
-- **Zero dependencies** — only React 18+ as peer dependency
-- **TypeScript-first** — complete types, full IDE autocomplete
-- **CSS Modules** — isolated styles, no global collisions
-- **API-friendly props** — `loading`, `debounceMs`, `validateOnBlur`, `onValueChange`
-- **Keyboard navigation** — full ARIA support, focus management
-- **Polish validators** — IBAN MOD-97, NIP/PESEL/REGON checksum built-in
+- GitHub: `https://github.com/Banzamel/mineralui`
+- npm: `https://www.npmjs.com/package/@banzamel/mineralui`
 
 ## License
 
-MIT — [Rafal Polak](https://bitbucket.org/polaczq/mineralui)
+MIT - Rafal Polak