@undefine-ui/design-system 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Undefine
+
+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,99 @@
+# @undefine-ui/design-system
+
+React component library + MUI theme layer extracted from the Define design system.
+
+## Installation
+
+```bash
+pnpm add @undefine-ui/design-system
+# peer deps you will already have in most React + MUI apps
+pnpm add @mui/material @mui/x-data-grid @emotion/react @emotion/styled react react-dom react-hook-form
+```
+
+## Usage
+
+### Providers
+
+Every consumer app needs the same provider stack that the showcase uses:
+
+```tsx
+import { SettingsProvider, defaultSettings, ThemeProvider } from '@undefine-ui/design-system';
+
+export function DesignSystemApp({ children }: { children: React.ReactNode }) {
+  return (
+    <SettingsProvider settings={defaultSettings}>
+      <ThemeProvider>{children}</ThemeProvider>
+    </SettingsProvider>
+  );
+}
+```
+
+- `SettingsProvider` exposes the design-system preferences (mode, contrast, fonts, nav layout) through the `useSettings` hook. Provide your own `settings` object if you want different defaults or if you persist user choices.
+- `ThemeProvider` wraps MUI’s CssVarsProvider with the Define theme (`createTheme`). It accepts any React children and automatically injects `CssBaseline`.
+- Both providers are exported from the package root so you can colocate them with your router/root layout.
+
+### Theming hooks
+
+If you need to read or update theme settings at runtime:
+
+```tsx
+import { useSettings } from '@undefine-ui/design-system';
+
+const ThemeSwitcher = () => {
+  const { colorScheme, onUpdateField } = useSettings();
+
+  return (
+    <ToggleButtonGroup
+      value={colorScheme}
+      onChange={(_, value) => value && onUpdateField('colorScheme', value)}
+    >
+      {/* buttons */}
+    </ToggleButtonGroup>
+  );
+};
+```
+
+`useSettings` is a thin wrapper around React context, so it must be used inside `SettingsProvider`.
+
+### Component imports
+
+```tsx
+import {
+  CopyButton,
+  Field,
+  Form,
+  Icon,
+  LoadingScreen,
+  Table,
+  Upload
+} from '@undefine-ui/design-system';
+```
+
+Storybook (`pnpm dev:storybook`) documents each component and token surface.
+
+## Export surface
+
+Everything is re-exported from `src/index.ts`. Key groups:
+
+| Group      | Exports                                                                                                                                                                    |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components | `CopyButton`, `HookForm` helpers (`Form`, `Field`, `RHFSwitch`, etc.), `Icon`, `Logo`, `LoadingScreen`, `Table`, `Upload`                                                  |
+| Hooks      | `useBoolean`, `useCopyToClipboard`, `useEventListener`, `useLocalStorage`, `useResponsive`, `useSettings`                                                                  |
+| Contexts   | `SettingsProvider`, `SettingsContext`, `defaultSettings`, `SettingsValueProps`                                                                                             |
+| Theme      | `ThemeProvider`, `createTheme`, `colorSchemes`, `components`, `palette`, `radius`, `shadows`, `customSpacing`, utilities such as `varAlpha`, `bgGradient`, `hideScrollX/Y` |
+| Utilities  | `changeCase` helpers, `formatNumber`, generic `helpers`                                                                                                                    |
+
+You can also import the theme pieces directly to compose your own MUI theme or to extend tokens in Storybook.
+
+## Customising the theme
+
+- Call `createTheme(settings)` to get the configured `Theme` object (useful for tests or SSR).
+- Theme tokens live under `src/theme/core`. If you need to override palette/typography/etc., spread the exports into your own `extendTheme` call.
+- `updateCoreWithSettings` and `updateComponentsWithSettings` are exported for advanced scenarios (e.g., you want to override the default settings object before rendering).
+
+## Scripts
+
+- `pnpm build` – bundle ESM/CJS output + `.d.ts` into `dist/`
+- `pnpm storybook` – run Storybook locally
+- `pnpm build-storybook` – static Storybook output
+- `pnpm test` – run Vitest (once specs are added)