@cmotino/cm-web-components 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# cm-web-components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A React component library built on Material UI.
+
+## Requirements
+
+- React 19 and MUI 9, with Emotion
+- ES modules only
+- TypeScript consumers need `moduleResolution` set to `bundler`, `node16` or `nodenext`
+
+## Theming
+
+`CmThemeProvider` applies the default look. Use `createCmTheme` to override it for your project:
+
+```tsx
+import { Button, CmThemeProvider, createCmTheme } from '@cmotino/cm-web-components'
+
+const theme = createCmTheme({
+  palette: { primary: { main: '#0b6e4f' } },
+  shape: { borderRadius: 4 },
+})
+
+export function App() {
+  return (
+    <CmThemeProvider theme={theme}>
+      <Button sx={{ mt: 2 }}>Save</Button>
+    </CmThemeProvider>
+  )
+}
+```
+
+**A top-level `palette` override only changes light mode.** To change dark mode, override `colorSchemes.dark`:
+
+```ts
+createCmTheme({
+  palette: { primary: { main: '#0b6e4f' } },
+  colorSchemes: { dark: { palette: { primary: { main: '#7fd8b6' } } } },
+})
+```
+
+**Colors follow the operating system by default.** For a manual light and dark toggle, set a color scheme selector:
+
+```ts
+createCmTheme({ cssVariables: { colorSchemeSelector: 'class' } })
+```
+
+`CmThemeProvider` adds no global styles. Pass `baseline` to include MUI's `CssBaseline`. The theme uses `Inter, sans-serif` but doesn't load the font, so load Inter in your project, for example with `@fontsource/inter`.
+
+**The default theme turns on MUI's keyboard focus ring for every MUI component.** Change it with `focusVisible`, or turn it off with `false`:
+
+```ts
+createCmTheme({ focusVisible: { outlineColor: '#0b6e4f' } })
+createCmTheme({ focusVisible: false })
+```
+
+## Button
+
+`Button` is MUI's `Button` with the library's default look: no uppercase text, no elevation and a keyboard focus ring. Every MUI prop works, including `loading`, `startIcon` and `component`:
+
+```tsx
+import { Button } from '@cmotino/cm-web-components'
+import { Link as RouterLink } from 'react-router'
+
+<Button variant="contained" loading={isSaving} onClick={handleSave}>Save</Button>
+
+<Button component={RouterLink} to="/settings">Settings</Button>
+```
+
+**Use an object for `styleOverrides.root`.** An object merges with the library defaults. A function replaces them, so the label goes back to uppercase unless the function sets `textTransform` itself:
+
+```ts
+createCmTheme({
+  components: {
+    MuiButton: { styleOverrides: { root: { fontWeight: 700 } } },
+  },
+})
+```
+
+**`ButtonProps` describes the `<button>` form only.** A wrapper of your own around the link form needs to declare link props such as `target` itself.
+
+The look comes from the theme, so without `CmThemeProvider` a `Button` renders with the surrounding MUI theme, and MUI's own `Button` used under the library theme gets the library look.
+
+## Development
+
+Use the Node version in `.nvmrc`, then:
+
+```sh
+npm install
+npm run dev
+```
+
+`npm run dev` starts Storybook. Before opening a pull request, run:
+
+```sh
+npm run lint && npm run typecheck && npm test && npm run build && npm run test:dist
+```
+
+Pull requests with user-facing changes need a changelog entry from `npm run changeset`.
+
+Design decisions are in [`docs/specs`](./docs/specs/README.md). Start with the [architecture spec](./docs/specs/0000-architecture.md) and the [roadmap](./docs/specs/roadmap.md).

package/dist/components/Button/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Button } from '@mui/material/Button';
+export type { ButtonProps } from '@mui/material/Button';

package/dist/components/Button/index.js

@@ -0,0 +1 @@
+export { default as Button } from "@mui/material/Button";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './components/Button/index.ts';
+export * from './theme/index.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+import { Button } from "./components/Button/index.js";
+import { createCmTheme } from "./theme/createCmTheme.js";
+import { CmThemeProvider } from "./theme/CmThemeProvider.js";
+export { Button, CmThemeProvider, createCmTheme };

package/dist/theme/CmThemeProvider.d.ts

@@ -0,0 +1,14 @@
+import type { Theme, ThemeProviderProps } from '@mui/material/styles';
+export interface CmThemeProviderProps extends Omit<ThemeProviderProps<Theme>, 'theme'> {
+    /**
+     * The theme to apply. Build one with `createCmTheme`.
+     * @default the library theme
+     */
+    theme?: ThemeProviderProps<Theme>['theme'];
+    /**
+     * If `true`, adds MUI's `CssBaseline` global styles.
+     * @default false
+     */
+    baseline?: boolean;
+}
+export declare function CmThemeProvider({ theme, baseline, children, ...other }: CmThemeProviderProps): import("react").JSX.Element;

package/dist/theme/CmThemeProvider.js

@@ -0,0 +1,51 @@
+"use client";
+import { createCmTheme } from "./createCmTheme.js";
+import { c } from "react/compiler-runtime";
+import CssBaseline from "@mui/material/CssBaseline";
+import { ThemeProvider } from "@mui/material/styles";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/theme/CmThemeProvider.tsx
+var libraryTheme = createCmTheme();
+function CmThemeProvider(t0) {
+	const $ = c(12);
+	let children;
+	let other;
+	let t1;
+	let t2;
+	if ($[0] !== t0) {
+		({theme: t1, baseline: t2, children, ...other} = t0);
+		$[0] = t0;
+		$[1] = children;
+		$[2] = other;
+		$[3] = t1;
+		$[4] = t2;
+	} else {
+		children = $[1];
+		other = $[2];
+		t1 = $[3];
+		t2 = $[4];
+	}
+	const theme = t1 === void 0 ? libraryTheme : t1;
+	const baseline = t2 === void 0 ? false : t2;
+	let t3;
+	if ($[5] !== baseline) {
+		t3 = baseline ? /* @__PURE__ */ jsx(CssBaseline, {}) : null;
+		$[5] = baseline;
+		$[6] = t3;
+	} else t3 = $[6];
+	let t4;
+	if ($[7] !== children || $[8] !== other || $[9] !== t3 || $[10] !== theme) {
+		t4 = /* @__PURE__ */ jsxs(ThemeProvider, {
+			theme,
+			...other,
+			children: [t3, children]
+		});
+		$[7] = children;
+		$[8] = other;
+		$[9] = t3;
+		$[10] = theme;
+		$[11] = t4;
+	} else t4 = $[11];
+	return t4;
+}
+export { CmThemeProvider };

package/dist/theme/createCmTheme.d.ts

@@ -0,0 +1,20 @@
+import type { Theme, ThemeOptions } from '@mui/material/styles';
+declare module '@mui/material/styles' {
+    interface Palette {
+        /** The shadow of `shadows[1]`, set per color scheme. */
+        baseShadow: string;
+    }
+    interface PaletteOptions {
+        baseShadow?: string;
+    }
+}
+/**
+ * Creates a theme from the library defaults and a project's overrides.
+ *
+ * A top-level `palette` override applies to the default color scheme only,
+ * which is light. To change dark mode, override `colorSchemes.dark`.
+ *
+ * The overrides must be merged before calling `createTheme`. With color
+ * schemes defined, `createTheme(defaults, overrides)` silently ignores them.
+ */
+export declare function createCmTheme(overrides?: ThemeOptions): Theme;

package/dist/theme/createCmTheme.js

@@ -0,0 +1,34 @@
+import { defaultThemeOptions } from "./defaultTheme.js";
+import { baseShadow } from "./tokens.js";
+import { createTheme } from "@mui/material/styles";
+import deepmerge from "@mui/utils/deepmerge";
+// src/theme/createCmTheme.ts
+var muiShadows;
+/**
+* MUI's shadows, with `shadows[1]` replaced by the color scheme's `baseShadow`.
+* Shadows can't differ between color schemes, so the CSS variable does that.
+*/
+function createShadows(options) {
+	const { cssVariables } = options;
+	const prefix = typeof cssVariables === "object" ? cssVariables.cssVarPrefix ?? "mui" : "mui";
+	const name = prefix ? `--${prefix}-palette-baseShadow` : "--palette-baseShadow";
+	muiShadows ??= createTheme().shadows;
+	const shadows = muiShadows.slice();
+	shadows[1] = `var(${name}, ${baseShadow.light})`;
+	return shadows;
+}
+/**
+* Creates a theme from the library defaults and a project's overrides.
+*
+* A top-level `palette` override applies to the default color scheme only,
+* which is light. To change dark mode, override `colorSchemes.dark`.
+*
+* The overrides must be merged before calling `createTheme`. With color
+* schemes defined, `createTheme(defaults, overrides)` silently ignores them.
+*/
+function createCmTheme(overrides = {}) {
+	const options = deepmerge(defaultThemeOptions, overrides);
+	options.shadows ??= createShadows(options);
+	return createTheme(options);
+}
+export { createCmTheme };

package/dist/theme/defaultTheme.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeOptions } from '@mui/material/styles';
+export declare const defaultThemeOptions: ThemeOptions;

package/dist/theme/defaultTheme.js

@@ -0,0 +1,148 @@
+import { baseShadow, brand, gray, green, orange, red } from "./tokens.js";
+import { alpha } from "@mui/material/styles";
+// src/theme/defaultTheme.ts
+var defaultThemeOptions = {
+	cssVariables: true,
+	colorSchemes: {
+		light: { palette: {
+			primary: {
+				light: brand[200],
+				main: brand[400],
+				dark: brand[700],
+				contrastText: brand[50]
+			},
+			info: {
+				light: brand[100],
+				main: brand[300],
+				dark: brand[600],
+				contrastText: gray[50]
+			},
+			warning: {
+				light: orange[300],
+				main: orange[400],
+				dark: orange[800]
+			},
+			error: {
+				light: red[300],
+				main: red[400],
+				dark: red[800]
+			},
+			success: {
+				light: green[300],
+				main: green[400],
+				dark: green[800]
+			},
+			grey: { ...gray },
+			divider: alpha(gray[300], .4),
+			background: {
+				default: "hsl(0, 0%, 99%)",
+				paper: "hsl(220, 35%, 97%)"
+			},
+			text: {
+				primary: gray[800],
+				secondary: gray[600]
+			},
+			action: {
+				hover: alpha(gray[200], .2),
+				selected: alpha(gray[200], .3)
+			},
+			baseShadow: baseShadow.light
+		} },
+		dark: { palette: {
+			primary: {
+				light: brand[300],
+				main: brand[400],
+				dark: brand[700],
+				contrastText: brand[50]
+			},
+			info: {
+				light: brand[500],
+				main: brand[700],
+				dark: brand[900],
+				contrastText: brand[300]
+			},
+			warning: {
+				light: orange[400],
+				main: orange[500],
+				dark: orange[700]
+			},
+			error: {
+				light: red[400],
+				main: red[500],
+				dark: red[700]
+			},
+			success: {
+				light: green[400],
+				main: green[500],
+				dark: green[700]
+			},
+			grey: { ...gray },
+			divider: alpha(gray[700], .6),
+			background: {
+				default: gray[900],
+				paper: "hsl(220, 30%, 7%)"
+			},
+			text: {
+				primary: "hsl(0, 0%, 100%)",
+				secondary: gray[400]
+			},
+			action: {
+				hover: alpha(gray[600], .2),
+				selected: alpha(gray[600], .3)
+			},
+			baseShadow: baseShadow.dark
+		} }
+	},
+	typography: {
+		fontFamily: "Inter, sans-serif",
+		h1: {
+			fontSize: "3rem",
+			fontWeight: 600,
+			lineHeight: 1.2,
+			letterSpacing: -.5
+		},
+		h2: {
+			fontSize: "2.25rem",
+			fontWeight: 600,
+			lineHeight: 1.2
+		},
+		h3: {
+			fontSize: "1.875rem",
+			lineHeight: 1.2
+		},
+		h4: {
+			fontSize: "1.5rem",
+			fontWeight: 600,
+			lineHeight: 1.5
+		},
+		h5: {
+			fontSize: "1.25rem",
+			fontWeight: 600
+		},
+		h6: {
+			fontSize: "1.125rem",
+			fontWeight: 600
+		},
+		subtitle1: { fontSize: "1.125rem" },
+		subtitle2: {
+			fontSize: "0.875rem",
+			fontWeight: 500
+		},
+		body1: { fontSize: "0.875rem" },
+		body2: {
+			fontSize: "0.875rem",
+			fontWeight: 400
+		},
+		caption: {
+			fontSize: "0.75rem",
+			fontWeight: 400
+		}
+	},
+	shape: { borderRadius: 8 },
+	focusVisible: true,
+	components: { MuiButton: {
+		defaultProps: { disableElevation: true },
+		styleOverrides: { root: { textTransform: "none" } }
+	} }
+};
+export { defaultThemeOptions };

package/dist/theme/index.d.ts

@@ -0,0 +1,3 @@
+export { CmThemeProvider } from './CmThemeProvider.tsx';
+export type { CmThemeProviderProps } from './CmThemeProvider.tsx';
+export { createCmTheme } from './createCmTheme.ts';

package/dist/theme/tokens.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Color scales for the default theme, taken from `references/theme/themePrimitives.ts`.
+ * They're private: components read colors from the theme, never from here.
+ */
+export declare const brand: {
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+};
+export declare const gray: {
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+};
+export declare const green: {
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+};
+export declare const orange: {
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+};
+export declare const red: {
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+};
+export declare const baseShadow: {
+    light: string;
+    dark: string;
+};

package/dist/theme/tokens.js

@@ -0,0 +1,70 @@
+// src/theme/tokens.ts
+/**
+* Color scales for the default theme, taken from `references/theme/themePrimitives.ts`.
+* They're private: components read colors from the theme, never from here.
+*/
+var brand = {
+	50: "hsl(210, 100%, 95%)",
+	100: "hsl(210, 100%, 92%)",
+	200: "hsl(210, 100%, 80%)",
+	300: "hsl(210, 100%, 65%)",
+	400: "hsl(210, 98%, 48%)",
+	500: "hsl(210, 98%, 42%)",
+	600: "hsl(210, 98%, 55%)",
+	700: "hsl(210, 100%, 35%)",
+	800: "hsl(210, 100%, 16%)",
+	900: "hsl(210, 100%, 21%)"
+};
+var gray = {
+	50: "hsl(220, 35%, 97%)",
+	100: "hsl(220, 30%, 94%)",
+	200: "hsl(220, 20%, 88%)",
+	300: "hsl(220, 20%, 80%)",
+	400: "hsl(220, 20%, 65%)",
+	500: "hsl(220, 20%, 42%)",
+	600: "hsl(220, 20%, 35%)",
+	700: "hsl(220, 20%, 25%)",
+	800: "hsl(220, 30%, 6%)",
+	900: "hsl(220, 35%, 3%)"
+};
+var green = {
+	50: "hsl(120, 80%, 98%)",
+	100: "hsl(120, 75%, 94%)",
+	200: "hsl(120, 75%, 87%)",
+	300: "hsl(120, 61%, 77%)",
+	400: "hsl(120, 44%, 53%)",
+	500: "hsl(120, 59%, 30%)",
+	600: "hsl(120, 70%, 25%)",
+	700: "hsl(120, 75%, 16%)",
+	800: "hsl(120, 84%, 10%)",
+	900: "hsl(120, 87%, 6%)"
+};
+var orange = {
+	50: "hsl(45, 100%, 97%)",
+	100: "hsl(45, 92%, 90%)",
+	200: "hsl(45, 94%, 80%)",
+	300: "hsl(45, 90%, 65%)",
+	400: "hsl(45, 90%, 40%)",
+	500: "hsl(45, 90%, 35%)",
+	600: "hsl(45, 91%, 25%)",
+	700: "hsl(45, 94%, 20%)",
+	800: "hsl(45, 95%, 16%)",
+	900: "hsl(45, 93%, 12%)"
+};
+var red = {
+	50: "hsl(0, 100%, 97%)",
+	100: "hsl(0, 92%, 90%)",
+	200: "hsl(0, 94%, 80%)",
+	300: "hsl(0, 90%, 65%)",
+	400: "hsl(0, 90%, 40%)",
+	500: "hsl(0, 90%, 30%)",
+	600: "hsl(0, 91%, 25%)",
+	700: "hsl(0, 94%, 18%)",
+	800: "hsl(0, 95%, 12%)",
+	900: "hsl(0, 93%, 6%)"
+};
+var baseShadow = {
+	light: "hsla(220, 30%, 5%, 0.07) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.07) 0px 8px 16px -5px",
+	dark: "hsla(220, 30%, 5%, 0.7) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.8) 0px 8px 16px -5px"
+};
+export { baseShadow, brand, gray, green, orange, red };

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@cmotino/cm-web-components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "scripts": {
+    "dev": "storybook dev -p 6006",
+    "build": "tsc -b && vite build && tsc -p tsconfig.build.json",
+    "build-storybook": "storybook build",
+    "lint": "eslint .",
+    "typecheck": "tsc -b",
+    "test": "vitest run --project unit",
+    "test:watch": "vitest --project unit",
+    "test:dist": "vitest run --project dist",
+    "changeset": "changeset",
+    "release": "npm run build && changeset publish"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@changesets/cli": "^3.0.3",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@eslint/js": "^10.0.1",
+    "@fontsource/inter": "^5.3.0",
+    "@mui/icons-material": "^9.5.0",
+    "@mui/material": "^9.5.0",
+    "@rolldown/plugin-babel": "^0.3.0",
+    "@storybook/addon-a11y": "^10.6.6",
+    "@storybook/addon-docs": "^10.6.6",
+    "@storybook/react-vite": "^10.6.6",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^24.19.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^10.14.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.7",
+    "globals": "^17.13.0",
+    "jsdom": "^31.0.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "storybook": "^10.6.6",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0"
+  },
+  "dependencies": {
+    "@mui/utils": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@emotion/react": "^11.0.0",
+    "@emotion/styled": "^11.0.0",
+    "@mui/material": "^9.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}