@xanui/ui 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/readme.md +103 -0
package/package.json
CHANGED
package/readme.md
CHANGED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# XanUI UI Library
|
|
2
|
+
|
|
3
|
+
XanUI is a React design-system toolkit powered by `@xanui/core`. It combines low-level primitives (e.g., `Box`, `Stack`, `Layer`) with application-ready components (e.g., `Accordion`, `Modal`, `Datatable`, `Toast`) so product teams can build polished surfaces quickly while keeping full control over styling tokens.
|
|
4
|
+
|
|
5
|
+
## Highlights
|
|
6
|
+
|
|
7
|
+
- **Unified prop surface** – every component extends the `Tag` API, so spacing, layout, breakpoints, and system tokens behave identically across the library.
|
|
8
|
+
- **Production-ready defaults** – the color palette, typography scale, shadows, and radii mirror modern SaaS expectations yet remain overridable.
|
|
9
|
+
- **Server compatible** – SSR-safe patterns ensure components render on the server and hydrate cleanly on the client.
|
|
10
|
+
- **Documentation first** – each component ships with a dedicated Markdown guide in `docs/`, ready for consumption by the upcoming Next.js documentation site.
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @xanui/ui
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Required peer packages (`react`, `react-dom`, `@xanui/core`, `@xanui/icons`) should already exist in your project; otherwise, install them alongside XanUI.
|
|
20
|
+
|
|
21
|
+
## Quick Start
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import ThemeProvider from '@xanui/ui/ThemeProvider';
|
|
25
|
+
import Box from '@xanui/ui/Box';
|
|
26
|
+
import Button from '@xanui/ui/Button';
|
|
27
|
+
|
|
28
|
+
export default function App() {
|
|
29
|
+
return (
|
|
30
|
+
<ThemeProvider theme="light">
|
|
31
|
+
<Box p={3} gap={2} display="flex" flexDirection="column">
|
|
32
|
+
<h1>Welcome</h1>
|
|
33
|
+
<Button color="brand" onClick={() => alert('Hello from XanUI!')}>
|
|
34
|
+
Get Started
|
|
35
|
+
</Button>
|
|
36
|
+
</Box>
|
|
37
|
+
</ThemeProvider>
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Theming and Tokens
|
|
43
|
+
|
|
44
|
+
`ThemeProvider` injects the active token set from `@xanui/core`. At the component level you can:
|
|
45
|
+
|
|
46
|
+
- Provide responsive props (`{ xs: 'column', md: 'row' }`) via `useBreakpointProps`.
|
|
47
|
+
- Override styles with `sx`/`sxr` objects or custom CSS classes via `baseClass`.
|
|
48
|
+
- Extend color templates by registering new palettes in the core theme manager.
|
|
49
|
+
|
|
50
|
+
## Documentation & Examples
|
|
51
|
+
|
|
52
|
+
- **Component guides** – `docs/<Component>.md` follows a consistent structure (overview → basic example → props table → scenario examples). These files serve both as standalone references and as the content source for the forthcoming Next.js docs site (`documentation/`).
|
|
53
|
+
- **Playground** – `example/` contains runnable demos that mirror the documentation examples.
|
|
54
|
+
|
|
55
|
+
Once the Next.js docs site scaffolding is complete, run it with:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
cd documentation
|
|
59
|
+
npm install
|
|
60
|
+
npm run dev
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Component Index
|
|
64
|
+
|
|
65
|
+
| Category | Components | Docs |
|
|
66
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
67
|
+
| Layout & Surfaces | Box, Stack, Container, GridContainer, GridItem, Paper, Layer, ViewBox, Divider | `docs/Box.md`, `docs/Stack.md`, `docs/Container.md`, `docs/GridContainer.md`, `docs/GridItem.md`, `docs/Paper.md`, `docs/Layer.md`, `docs/ViewBox.md`, `docs/Divider.md` |
|
|
68
|
+
| Navigation | Tabs, Tab, List, ListItem, Menu, Drawer | `docs/Tabs.md`, `docs/Tab.md`, `docs/List.md`, `docs/ListItem.md`, `docs/Menu.md`, `docs/Drawer.md` |
|
|
69
|
+
| Data Display | Table (and TableBody/TableCell/TableFooter/TableHead/TablePagination/TableRow), Datatable, Chip, Avatar, Image, Badge, CircleProgress, LineProgress, LoadingBox | `docs/Table*.md`, `docs/Datatable.md`, `docs/Chip.md`, `docs/Avatar.md`, `docs/Image.md`, `docs/Badge.md`, `docs/CircleProgress.md`, `docs/LineProgress.md`, `docs/LoadingBox.md` |
|
|
70
|
+
| Inputs & Forms | Button, ButtonGroup, IconButton, Form, Input, Select, Option, Checkbox, Radio, Switch, Calendar, CalendarInput, Label | `docs/Button.md`, `docs/ButtonGroup.md`, `docs/IconButton.md`, `docs/Form.md`, `docs/Input.md`, `docs/Select.md`, `docs/Option.md`, `docs/Checkbox.md`, `docs/Radio.md`, `docs/Switch.md`, `docs/Calendar.md`, `docs/CalendarInput.md`, `docs/Label.md` |
|
|
71
|
+
| Disclosure & Feedback | Accordion, Collaps, Alert, Toast, Tooltip, Modal, Portal, Scrollbar, Toast, NoSSR | `docs/Accordion.md`, `docs/Collaps.md`, `docs/Alert.md`, `docs/Toast.md`, `docs/Tooltip.md`, `docs/Modal.md`, `docs/Portal.md`, `docs/Scrollbar.md`, `docs/NoSSR.md` |
|
|
72
|
+
| Typography & Utilities | Text, ThemeProvider, useCorner, ClickOutside, View helpers | `docs/Text.md`, `docs/ThemeProvider.md`, `docs/useCorner.md`, `docs/ClickOutside.md`, `docs/ViewBox.md` |
|
|
73
|
+
|
|
74
|
+
> The full list is available in `docs/`. Each entry adheres to the shared documentation template for easy navigation and consistency.
|
|
75
|
+
|
|
76
|
+
## Local Development
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npm install
|
|
80
|
+
npm run start # runs makepack dev server plus the example playground
|
|
81
|
+
npm run build # bundles the library via makepack
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The development workflow encourages updating `docs/` alongside the corresponding component so examples stay truthful. The `example/` playground hot-reloads component changes for rapid iteration.
|
|
85
|
+
|
|
86
|
+
## Contributing
|
|
87
|
+
|
|
88
|
+
1. Fork this repository and clone your fork.
|
|
89
|
+
2. Install dependencies via `npm install`.
|
|
90
|
+
3. Implement your change (component, hook, docs, or tooling) inside `src/` and update/author `docs/<Component>.md` accordingly.
|
|
91
|
+
4. Run `npm run start` to validate the example playground and lint output.
|
|
92
|
+
5. Open a pull request with a clear description, screenshots when UI changes occur, and reference to relevant documentation updates.
|
|
93
|
+
|
|
94
|
+
Guidelines:
|
|
95
|
+
|
|
96
|
+
- Keep new components aligned with the `TagProps` surface (spacing, layout, color tokens, responsive props).
|
|
97
|
+
- Provide at least one example in `example/` when adding new UI patterns.
|
|
98
|
+
- Maintain the established documentation structure (overview, basic example, props table, scenario demos).
|
|
99
|
+
|
|
100
|
+
## License
|
|
101
|
+
|
|
102
|
+
Distributed under the MIT License. Refer to `LICENSE` for full text.
|
|
103
|
+
|