@maomaolabs/core 1.0.2 → 1.1.0

package/README.md

@@ -9,6 +9,7 @@
   <p>
     <a href="https://www.npmjs.com/package/@maomaolabs/core"><img src="https://img.shields.io/npm/v/@maomaolabs/core?style=for-the-badge&color=000000" alt="NPM Version" /></a>
     <a href="https://github.com/maomaolabs/core/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@maomaolabs/core?style=for-the-badge&color=000" alt="License" /></a>
+    <a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Changelog-📖-000000?style=for-the-badge" alt="Changelog" /></a>
     <img src="https://img.shields.io/badge/React-18.0.0+-blue?style=for-the-badge&logo=react&color=000000" alt="React 18+" />
   </p>
 
@@ -168,7 +169,7 @@ const OpenAppCounter = () => {
 
 | Component | Description | Props |
 | :--- | :--- | :--- |
-| `WindowSystemProvider` | Root context provider. Wrap your entire app with this. | `children: ReactNode` |
+| `WindowSystemProvider` | Root context provider. Wrap your entire app with this. | `children: ReactNode`, `systemStyle?: SystemStyle` |
 | `WindowManager` | Renders all active windows and snap preview overlays. | — |
 | `Toolbar` | Taskbar with app launchers and folder support. | `toolbarItems: ToolbarItem[]`, `showLogo?: boolean` |
 
@@ -209,6 +210,8 @@ Returns `{ snapPreview, setSnapPreview }` for reading and controlling the active
 | `canMinimize` | `boolean` | — | Shows the minimize control. |
 | `canMaximize` | `boolean` | — | Shows the maximize/restore control. |
 | `canClose` | `boolean` | — | Shows the close control. |
+| `className` | `string` | — | Inject custom CSS classes directly into the window container. |
+| `style` | `React.CSSProperties` | — | Inject inline styles overriding or extending window container styles. |
 
 #### `FolderDefinition`
 
@@ -221,6 +224,15 @@ Returns `{ snapPreview, setSnapPreview }` for reading and controlling the active
 
 > `ToolbarItem = WindowDefinition | FolderDefinition`
 
+#### `WindowStyling`
+
+Exported type available for reuse in your own components:
+
+```ts
+import type { WindowStyling } from '@maomaolabs/core';
+// { className?: string; style?: React.CSSProperties }
+```
+
 ---
 
 ## ⚙️ Styling
@@ -233,6 +245,94 @@ import '@maomaolabs/core/dist/style.css';
 
 Ensure your bundler (Vite, Webpack, etc.) is configured to process CSS from `node_modules`.
 
+### Theming System (`systemStyle`)
+
+The context provider accepts a `systemStyle` prop that governs the aesthetics of the entire rendered window manager system:
+
+```tsx
+<WindowSystemProvider systemStyle="aero">
+```
+
+Pre-bundled themes include:
+- `default`
+- `traffic` (colored dot buttons concept)
+- `linux` (modern dark/light gradient adaptation)
+- `yk2000` (classic 90s/00s retro styling)
+- `aero` (translucent glass blurring)
+
+**Note on Custom Themes**: `SystemStyle` strictly autocompletes the pre-built themes above, but mathematically permits *any* string to be passed via Type relaxation. You can pass your own `systemStyle="my-custom-theme"` alongside injected custom CSS.
+
+### Custom Theme Injection
+
+You can define your own theme by creating a CSS file that targets the `data-system-style` attribute.
+
+> ⚠️ Use standard CSS attribute selectors — **avoid `:global()`** unless your bundler explicitly supports it (e.g. CSS Modules with PostCSS).
+
+```css
+/* my-custom-theme.css */
+[data-system-style="my-custom-theme"] .window-header {
+  background: #1a1a2e;
+  color: #e0e0e0;
+}
+
+[data-system-style="my-custom-theme"] .window-controls {
+  gap: 6px;
+}
+```
+
+Import the CSS file anywhere in your app (e.g. `src/index.tsx`) before the provider renders:
+
+```tsx
+import './my-custom-theme.css';
+```
+
+Then pass the identifier to the provider:
+
+```tsx
+<WindowSystemProvider systemStyle="my-custom-theme">
+  {/* ... */}
+</WindowSystemProvider>
+```
+
+#### Available CSS selectors
+
+The following global class names are always present on the window DOM and safe to target in your theme:
+
+| Selector | Element |
+| :--- | :--- |
+| `.window-container` | Root window wrapper |
+| `.window-header` | Title bar (drag area) |
+| `.window-title` | Title text container |
+| `.window-icon` | Icon inside the title bar |
+| `.window-controls` | Button group (minimize / maximize / close) |
+| `.terminal-btn` | Generic control button |
+| `.window-scrollbar` | Scrollable content area |
+| `.window-resize-handle` | Bottom-right resize grip |
+
+You can also target individual buttons via the `data-action` attribute:
+
+```css
+[data-system-style="my-custom-theme"] [data-action="close"] { background: red; }
+[data-system-style="my-custom-theme"] [data-action="maximize"] { background: green; }
+[data-system-style="my-custom-theme"] [data-action="minimize"] { background: yellow; }
+```
+
+#### Per-window inline overrides
+
+Custom `className` and `style` props are accepted on each individual window definition via `openWindow()`, allowing per-instance overrides on top of the global theme:
+
+```tsx
+openWindow({
+  id: 'my-app',
+  title: 'My App',
+  component: <div />,
+  className: 'my-extra-class',
+  style: { borderRadius: '16px', border: '1px solid #444' },
+});
+```
+
+These are merged after the global theme styles, so they always take precedence.
+
 ---
 
 ## 🤝 Contributing

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export declare type FolderDefinition = {
     apps: WindowDefinition[];
 };
 
+declare type SystemStyle = (string & {}) | 'default' | 'traffic' | 'linux' | 'yk2000' | 'aero';
+
 /**
  * Main toolbar component. Provides all options available to open windows.
  * @param windows - Array of window instances to be displayed in the toolbar.
@@ -61,6 +63,12 @@ export declare function useWindowSnap(): {
 declare const Window_2: React_2.NamedExoticComponent<WindowProps>;
 export { Window_2 as Window }
 
+export declare type WindowBehavior = {
+    canMinimize?: boolean;
+    canMaximize?: boolean;
+    canClose?: boolean;
+};
+
 export declare type WindowContextState = {
     size: {
         width: number;
@@ -83,15 +91,17 @@ export declare type WindowContextState = {
     windowRef: React_2.RefObject<HTMLDivElement>;
 };
 
-/**
- * WindowDefinition type.
- * Defines the properties of a window.
- */
-export declare type WindowDefinition = {
+export declare type WindowCore = {
     id: string;
-    title: string;
-    icon?: React_2.ReactNode;
-    component: React_2.ReactNode;
+    layer?: 'base' | 'normal' | 'alwaysOnTop' | 'modal';
+    isMaximized?: boolean;
+};
+
+export declare type WindowDefinition = WindowCore & WindowPresentation & WindowGeometry & WindowBehavior & WindowStyling;
+
+export declare type WindowDispatch = Omit<WindowSystemProvider_2, 'windows' | 'snapPreview' | 'setSnapPreview'>;
+
+export declare type WindowGeometry = {
     initialSize?: {
         width: number;
         height: number;
@@ -100,15 +110,8 @@ export declare type WindowDefinition = {
         x: number;
         y: number;
     };
-    layer?: 'base' | 'normal' | 'alwaysOnTop' | 'modal';
-    isMaximized?: boolean;
-    canMinimize?: boolean;
-    canMaximize?: boolean;
-    canClose?: boolean;
 };
 
-export declare type WindowDispatch = Omit<WindowSystemProvider_2, 'windows' | 'snapPreview' | 'setSnapPreview'>;
-
 export declare type WindowHeaderProps = {
     onClose: () => void;
     title: string;
@@ -145,11 +148,31 @@ export declare type WindowInstance = Omit<WindowDefinition, 'initialSize' | 'ini
  */
 export declare function WindowManager(): JSX_2.Element;
 
+/**
+ * WindowDefinition type.
+ * Defines the properties of a window.
+ */
+export declare type WindowPresentation = {
+    title: string;
+    icon?: React_2.ReactNode;
+    component: React_2.ReactNode;
+};
+
 export declare type WindowProps = {
     window: WindowInstance;
 };
 
-export declare function WindowSystemProvider({ children }: WindowSystemProviderProps): JSX_2.Element;
+/**
+ * WindowStyling type.
+ * Allows consumers to inject custom className and style into the window container.
+ * Kept separate from WindowPresentation to avoid collisions with HTML attribute names (e.g. `title`).
+ */
+export declare type WindowStyling = {
+    className?: string;
+    style?: React_2.CSSProperties;
+};
+
+export declare function WindowSystemProvider({ children, systemStyle }: WindowSystemProviderProps): JSX_2.Element;
 
 /**
  * WindowSystemProvider type.
@@ -167,10 +190,12 @@ declare type WindowSystemProvider_2 = {
     closeWindow: (id: string) => void;
     focusWindow: (id: string) => void;
     updateWindow: (id: string, data: Partial<WindowInstance>) => void;
+    systemStyle?: SystemStyle;
 };
 
 declare interface WindowSystemProviderProps {
     children: ReactNode;
+    systemStyle?: SystemStyle;
 }
 
 export { }