@banzamel/mineralui 0.2.0 → 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

@@ -0,0 +1,192 @@
+# MineralUI
+
+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
+
+```bash
+npm install @banzamel/mineralui
+```
+
+```tsx
+import '@banzamel/mineralui/styles.css'
+```
+
+## Quick Start
+
+```tsx
+import {
+    MThemeProvider,
+    MButton,
+    MCard,
+    MCardBody,
+    MCardHeader,
+    MInput,
+    MSelect,
+    MStack,
+} from '@banzamel/mineralui'
+import '@banzamel/mineralui/styles.css'
+
+function AccountSettings() {
+    return (
+        <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>
+    )
+}
+```
+
+## What Is Included
+
+### 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
+- `MButton`
+- `MCheckbox`
+- `MRadio`, `MRadioGroup`
+- `MToggle`
+
+### Inputs
+- `MInput`, `MTextarea`
+- `MInputPassword`, `MInputNumber`, `MInputSearch`, `MInputEmail`
+- `MInputPhone`, `MInputName`, `MInputIBAN`, `MInputTaxId`, `MInputCurrency`
+- `MInputCreditCard`, `MInputPostCode`
+- `MInputGroup`
+
+### Dropdowns
+- `MSelect`
+- `MAutocomplete`
+- `MDatePicker`
+- `MDateRangePicker`
+- `MTimePicker`
+
+### 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`
+
+### Hooks and utilities
+- `mergeClasses`
+- `useDebounce`, `useDebouncedCallback`
+- `useOutsideClick`
+- `useKeyNavigation`
+- `useClickEffect`
+
+## Design System Notes
+
+MineralUI is driven by CSS variables and readable class names.
+
+```css
+:root {
+    --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);
+}
+```
+
+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
+
+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
+
+## 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.
+
+### 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.
+
+### 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
+```
+
+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
+
+- GitHub: `https://github.com/Banzamel/mineralui`
+- npm: `https://www.npmjs.com/package/@banzamel/mineralui`
+
+## License
+
+MIT - Rafal Polak