@mila_studios/mycelia-design-system 0.1.1

package/README.md

@@ -0,0 +1,187 @@
+# mycelia-design-system
+
+React component library **`@mila-studios/mycelia-design-system`**, available on [npm](https://www.npmjs.com/package/@mila-studios/mycelia-design-system). Source under [`packages/ui`](packages/ui). **React**, **Tailwind v4**, Radix-style primitives. To preview everything in the browser first, see [Run the demo locally](#run-the-demo-locally).
+
+---
+
+## Run the demo locally
+
+If you only want to **browse the component showcase** in the browser (no separate app to wire up), clone this repo, install, and start the bundled demo (esbuild + PostCSS watch):
+
+```bash
+git clone https://github.com/mila-studios/mila-design-components.git
+cd mila-design-components
+npm install
+npm run dev
+```
+
+Then open the URL printed in the terminal (esbuild’s dev server defaults to **http://localhost:8000**). The demo lives under [`packages/ui/src/demo`](packages/ui/src/demo) and is not part of the published npm package.
+
+---
+
+## Install and use in your app
+
+**Requirements:** Node 20+, npm 10+, React 18 or 19.
+
+1. Create an app (example: Vite + React + TS):
+
+   ```bash
+   npm create vite@latest my-app -- --template react-ts
+   cd my-app
+   ```
+
+2. Install the package from npm:
+
+   ```bash
+   npm install @mila-studios/mycelia-design-system
+   ```
+
+   **Or** add to `package.json`:
+
+   ```json
+   {
+     "dependencies": {
+       "@mila-studios/mycelia-design-system": "^0.1.0",
+       "react": "^19.0.0",
+       "react-dom": "^19.0.0"
+     }
+   }
+   ```
+   
+3. In **`src/main.tsx`**, import styles **first**:
+
+   ```tsx
+   import "@mila-studios/mycelia-design-system/styles.css"
+   ```
+
+   Fallback: `import "@mila-studios/mycelia-design-system/mycelia-ui.css"`. Charts that use **Recharts** may need `npm install recharts` in your app if the bundler does not hoist it.
+
+4. In **`src/App.tsx`**, import by file name (no `.tsx`), then run `npm run dev`:
+
+   ```tsx
+   import { Button } from "@mila-studios/mycelia-design-system/components/button"
+
+   export default function App() {
+     return (
+       <main>
+         <Button type="button">Hello</Button>
+       </main>
+     )
+   }
+   ```
+
+**Imports:** `@mila-studios/mycelia-design-system/components/<name>` and `@mila-studios/mycelia-design-system/lib/utils` (`cn` helper). The pre-built CSS covers classes used **inside this library**. For Tailwind utilities **only in your app files**, add PostCSS + `@mila-studios/mycelia-design-system/globals.css` + Tailwind `@source` for your sources (see [`packages/ui/src/styles/globals.css`](packages/ui/src/styles/globals.css)).
+
+---
+
+## Components
+
+Paths follow **`@mila-studios/mycelia-design-system/components/<file>`** (file name without `.tsx`). Grouped by role; each file exports the primitives you expect from a shadcn-style setup.
+
+| Area | Components |
+| --- | --- |
+| **Actions** | `button`, `icon-button` |
+| **Forms & inputs** | `input`, `textarea`, `label`, `checkbox`, `radio-group`, `switch`, `input-otp`, `input-file`, `combobox`, `calendar`, `date-picker`, `slider` |
+| **Layout & structure** | `card`, `separator`, `scroll-area`, `resizable`, `aspect-ratio` |
+| **Dialogs & overlays** | `dialog`, `alert-dialog`, `drawer`, `sheet`, `popover`, `hover-card`, `tooltip` |
+| **Navigation** | `tabs`, `breadcrumb`, `navigation-menu`, `pagination`, `sidebar`, `command`, `command-menu` |
+| **Data** | `table`, `data-table` (TanStack Table), `badge`, `avatar`, `avatar-stack`, `carousel` |
+| **Feedback** | `alert`, `accordion`, `progress`, `spinner`, `skeleton`, `sonner` (toasts) |
+| **Charts** | `chart` — MILA-themed wrappers around **Recharts** (`ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, …). Compose with `recharts` exports (`LineChart`, `BarChart`, `Area`, `XAxis`, …). |
+
+**Notable details**
+
+- **`input`** — MILA sizes: `mini` \| `sm` \| `default` \| `lg`; optional `startAdornment` / `endAdornment`. [Figma — Obra / MILA inputs](https://www.figma.com/design/G7n3jEe1IuqWPezoBhE1Lj/Obra-shadcn-ui---MILA?node-id=16-1738).
+- **`data-table`** — Built on `@tanstack/react-table` (already a dependency of the library).
+- **`chart`** — Use with `recharts`; tokens for grid, axes, and tooltips come from `globals.css` / `styles.css`.
+- **`sonner`** — Toaster; wrap your app with your framework’s pattern and render `<Toaster />` where appropriate.
+
+---
+
+## Repo layout (contributors)
+
+| Path | Purpose |
+| --- | --- |
+| Root `package.json` | Package **`@mila-studios/mycelia-design-system`**, `exports`, published `files` |
+| [`packages/ui`](packages/ui) | Components, [`globals.css`](packages/ui/src/styles/globals.css), build output in [`packages/ui/dist`](packages/ui/dist), pre-built [`mycelia-ui.css`](packages/ui/dist/mycelia-ui.css) |
+| [`packages/ui/src/demo`](packages/ui/src/demo) | Local demo (esbuild + PostCSS), not part of the npm JS bundle |
+
+**Contributors:** `npm install` → `npm run dev` (demo), `npm run build` (library + CSS). `packages/ui/dist` and root `mycelia-ui.css` are build outputs (gitignored); `prepare` runs the build when installing from a full clone so consumers get compiled assets.
+
+**shadcn CLI** (add components into `packages/ui`):
+
+```bash
+npx shadcn@latest add <component> -c packages/ui/components.json
+```
+
+---
+
+## Scripts (this repo)
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Demo dev server + CSS watch |
+| `npm run build` | Library (`tsup`) + `mycelia-ui.css` |
+| `npm run lint` / `npm run typecheck` / `npm run format` | Quality checks for `packages/ui` |
+
+---
+
+## Contributing
+
+This project uses [semantic-release](https://github.com/semantic-release/semantic-release) with [conventional commits](https://www.conventionalcommits.org/) for automated versioning. Your commit messages determine the next version number.
+
+### Commit Message Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types and Version Impact
+
+| Type | Description | Version Bump | Example |
+|------|-------------|--------------|---------|
+| `feat` | New feature | Minor (0.1.0 → 0.2.0) | `feat(button): add loading state` |
+| `fix` | Bug fix | Patch (0.1.0 → 0.1.1) | `fix(input): correct border color on focus` |
+| `feat!` | Breaking change | Major (0.1.0 → 1.0.0) | `feat(api)!: rename Button to Btn` |
+| `docs` | Documentation only | No release | `docs: update install instructions` |
+| `style` | Code style (formatting) | No release | `style: fix indentation` |
+| `refactor` | Code change (no fix/feat) | No release | `refactor(card): simplify props` |
+| `test` | Add/update tests | No release | `test(button): add click handler tests` |
+| `chore` | Maintenance tasks | No release | `chore: update dependencies` |
+
+### Examples
+
+**Patch release** (bug fix):
+```
+fix(tooltip): prevent overflow on long content
+
+The tooltip now properly wraps text and respects max-width.
+```
+
+**Minor release** (new feature):
+```
+feat(sidebar): add collapsible mode
+
+- Add `collapsible` prop to Sidebar component
+- Add `onCollapse` callback
+- Update styles for collapsed state
+```
+
+**Major release** (breaking change):
+```
+feat(theme)!: migrate to CSS custom properties
+
+BREAKING CHANGE: Theme tokens are now CSS variables.
+Replace `theme.colors.primary` with `var(--color-primary)`.
+```
+
+### Scope (optional)
+
+The scope identifies the component or area affected:
+- `feat(button):` — Button component
+- `fix(data-table):` — DataTable component
+- `docs(readme):` — README changes