@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/docs/Troubleshooting.md

@@ -0,0 +1,674 @@
+# Troubleshooting
+
+Common issues and solutions for the Mixtape Design System.
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [Build Errors](#build-errors)
+- [TypeScript Errors](#typescript-errors)
+- [CSS Issues](#css-issues)
+- [Storybook Issues](#storybook-issues)
+- [Test Failures](#test-failures)
+- [Runtime Errors](#runtime-errors)
+
+---
+
+## Installation Issues
+
+### pnpm install fails
+
+**Problem:** Dependencies fail to install
+
+**Solutions:**
+
+```bash
+# 1. Clear cache
+rm -rf node_modules
+rm pnpm-lock.yaml
+
+# 2. Reinstall
+pnpm install
+
+# 3. If still failing, try force reinstall
+pnpm install --force
+
+# 4. Check pnpm version (need v9+)
+pnpm --version
+```
+
+### Wrong Node version
+
+**Problem:** `Error: The engine "node" is incompatible`
+
+**Solution:**
+
+```bash
+# Check Node version (need v20+)
+node --version
+
+# Install correct version with nvm
+nvm install 20
+nvm use 20
+
+# Or with volta
+volta install node@20
+```
+
+### Missing dependencies
+
+**Problem:** `Cannot find module '@pnx-mixtape/ids-shape'`
+
+**Solution:**
+
+```bash
+# Install all dependencies
+pnpm install
+
+# Check workspace configuration
+cat pnpm-workspace.yaml
+```
+
+---
+
+## Build Errors
+
+### Vite build fails
+
+**Problem:** `Error: Build failed with X errors`
+
+**Solutions:**
+
+```bash
+# 1. Clean build directory
+rm -rf dist
+
+# 2. Clear Vite cache
+rm -rf node_modules/.vite
+
+# 3. Rebuild
+pnpm build-vite
+
+# 4. Check for TypeScript errors
+pnpm lint-ts
+```
+
+### PostCSS errors
+
+**Problem:** `Error: Cannot find module 'postcss-design-tokens'`
+
+**Solution:**
+
+```bash
+# Install PostCSS dependencies
+pnpm install -D postcss-design-tokens
+
+# Check PostCSS config
+cat vite.config.js
+```
+
+### Import errors
+
+**Problem:** `Error: Failed to resolve import`
+
+**Solutions:**
+
+```typescript
+// ❌ Bad - Relative imports
+import Component from '../../../Component/Card/Card'
+
+// ✅ Good - Use absolute paths or package imports
+import Component from '@pnx-mixtape/mxds/src/Component/Card/Card'
+
+// Or configure path aliases in vite.config.js
+resolve: {
+  alias: {
+    '@': path.resolve(__dirname, './src'),
+  },
+}
+```
+
+---
+
+## TypeScript Errors
+
+### Type errors in Web Components
+
+**Problem:** `Property 'popover' does not exist on type 'HTMLElement'`
+
+**Solution:**
+
+```typescript
+// Use @ts-expect-error with explanation
+// @ts-expect-error popover API not in TypeScript yet
+element.popover = "auto"
+
+// Or extend types
+declare global {
+  interface HTMLElement {
+    popover?: string
+  }
+}
+```
+
+### Type errors with refs
+
+**Problem:** `Object is possibly 'null'`
+
+**Solution:**
+
+```typescript
+// ❌ Bad
+popoverRef.current.showPopover()
+
+// ✅ Good - Check for null
+if (popoverRef.current) {
+  popoverRef.current.showPopover()
+}
+
+// Or use optional chaining
+popoverRef.current?.showPopover()
+```
+
+### Type errors with event handlers
+
+**Problem:** `Type '(e: MouseEvent) => void' is not assignable`
+
+**Solution:**
+
+```typescript
+// Specify correct event type
+handleClick = (e: MouseEvent): void => {
+  // ...
+}
+
+// Or use React types
+import { MouseEventHandler } from "react"
+handleClick: MouseEventHandler = e => {
+  // ...
+}
+```
+
+### JSX errors in consumer projects that path-map into `src/`
+
+**Problem:** A consuming project that path-maps directly into `node_modules/@pnx-mixtape/mxds/src/...` (instead of the built `dist` output) sees an error like this in `FormSelect.tsx`, even if it doesn't import `FormSelect` directly:
+
+```
+error TS2339: Property 'selectedcontent' does not exist on type 'JSX.IntrinsicElements'.
+```
+
+**Cause:** Mixtape declares custom elements like `<selectedcontent>` via a global JSX augmentation in `src/Utility/global.d.ts`. TypeScript only applies a global ambient declaration when that file is part of the active compiler program. If a consumer's `tsconfig.json` path-maps a barrel file (e.g. `@pnx-mixtape/mxds/src/react` → `src/react.ts`) without also including `global.d.ts`, every re-exported component — including ones the consumer never imports — gets type-checked without the augmentation, producing a false-positive error.
+
+**Solution:** In the consuming project's `tsconfig.json`, explicitly add mixtape's `global.d.ts` so it's part of the program. If `exclude` contains `"node_modules"`, add the file under `"files"` rather than `"include"` — `exclude` filters matches from `"include"` (even an exact path) but not `"files"`:
+
+```json
+{
+  "include": ["src"],
+  "files": ["node_modules/@pnx-mixtape/mxds/src/Utility/global.d.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+This only affects projects that path-map directly into mxds's `src/` (rather than consuming the built `dist` output) — a common setup for live design-system development.
+
+---
+
+## CSS Issues
+
+### Custom media not working
+
+**Problem:** `@media (--medium-up) not recognized`
+
+**Solution:**
+
+```css
+/* ✅ Always import at top of file */
+@import "../../_custom-media.css";
+
+.mx-component {
+  @media (--medium-up) {
+    /* styles */
+  }
+}
+```
+
+### BEM linting errors
+
+**Problem:** `Expected class selector to be BEM`
+
+**Solutions:**
+
+```css
+/* ❌ Bad */
+.mx-card-header {
+}
+.mx-card.active {
+}
+
+/* ✅ Good */
+.mx-card__header {
+}
+.mx-card--active {
+}
+```
+
+### Logical properties errors
+
+**Problem:** `Expected 'padding-left' to be 'padding-inline-start'`
+
+**Solution:**
+
+```css
+/* ❌ Bad */
+padding-left: 1rem;
+margin-top: 1rem;
+
+/* ✅ Good */
+padding-inline-start: 1rem;
+margin-block-start: 1rem;
+
+/* Exception: float is allowed */
+float: left; /* OK */
+```
+
+### Design tokens not working
+
+**Problem:** `token("colour.primary") not resolving`
+
+**Solution:**
+
+```javascript
+// Check PostCSS config includes tokens
+import { defineConfig } from "vite"
+import tokens from "./src/tokens.js"
+
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [require("postcss-design-tokens")({ tokens })],
+    },
+  },
+})
+```
+
+---
+
+## Storybook Issues
+
+### Storybook won't start
+
+**Problem:** `Error: Cannot start Storybook`
+
+**Solutions:**
+
+```bash
+# 1. Clear Storybook cache
+rm -rf node_modules/.cache/storybook
+
+# 2. Rebuild
+pnpm dev
+
+# 3. Check ports are available
+lsof -i :6006
+lsof -i :6008
+
+# 4. Kill existing processes
+kill -9 <PID>
+```
+
+### Stories not showing
+
+**Problem:** Stories don't appear in Storybook
+
+**Solution:**
+
+```typescript
+// Check story file is named correctly
+// ✅ Good
+Component.stories.ts
+Component.stories.tsx
+
+// ❌ Bad
+Component.story.ts
+component-stories.ts
+
+// Check stories glob in .storybook/main.ts
+export default {
+  stories: ["../src/**/*.stories.@(ts|tsx)"],
+}
+```
+
+### Addon errors
+
+**Problem:** `Error: Addon '@storybook/addon-a11y' not found`
+
+**Solution:**
+
+```bash
+# Install missing addons
+pnpm install -D @storybook/addon-a11y
+
+# Check .storybook/main.ts
+export default {
+  addons: [
+    '@storybook/addon-a11y',
+    // ... other addons
+  ],
+}
+```
+
+---
+
+## Test Failures
+
+### Snapshots failing
+
+**Problem:** `Snapshot doesn't match`
+
+**Solutions:**
+
+```bash
+# 1. Review what changed
+pnpm test
+
+# 2. Check diff
+git diff src/**/__snapshots__/
+
+# 3. If intentional, update snapshots
+pnpm test -- -u
+
+# 4. Review updated snapshots
+git diff src/**/__snapshots__/
+
+# 5. Commit if correct
+git add src/**/__snapshots__/
+git commit -m "test: update snapshots"
+```
+
+### Tests timing out
+
+**Problem:** `Error: Test timeout of 5000ms exceeded`
+
+**Solutions:**
+
+```bash
+# 1. Increase timeout
+pnpm test -- --testTimeout=30000
+
+# 2. Check Storybook is running
+curl http://localhost:6006
+
+# 3. Start Storybook manually
+pnpm dev-html
+pnpm dev-react
+
+# 4. Run tests
+pnpm test
+```
+
+### A11y test failures
+
+**Problem:** `Accessibility violation: color-contrast`
+
+**Solution:**
+
+```css
+/* Check contrast ratio */
+/* WCAG AA requires ≥ 4.5:1 for text */
+
+/* ❌ Bad - Insufficient contrast */
+color: #999;
+background: #fff; /* 2.85:1 - Fails */
+
+/* ✅ Good - Sufficient contrast */
+color: #666;
+background: #fff; /* 5.74:1 - Passes */
+```
+
+---
+
+## Runtime Errors
+
+### Component not registering
+
+**Problem:** `Failed to execute 'define' on 'CustomElementRegistry'`
+
+**Solution:**
+
+```typescript
+// Check component isn't already registered
+if (!customElements.get("mx-component")) {
+  customElements.define("mx-component", Component)
+}
+
+// Or handle error
+try {
+  customElements.define("mx-component", Component)
+} catch (e) {
+  console.warn("Component already registered")
+}
+```
+
+### Observer not disconnecting
+
+**Problem:** Memory leak with observers
+
+**Solution:**
+
+```typescript
+// ✅ Store observer as property
+class Component extends HTMLElement {
+  iO: IntersectionObserver
+
+  connectedCallback() {
+    this.iO = new IntersectionObserver(...)
+  }
+
+  disconnectedCallback() {
+    this.iO?.disconnect()  // Clean up
+  }
+}
+```
+
+### Event listeners not removing
+
+**Problem:** Listeners persist after component removed
+
+**Solution:**
+
+```typescript
+// ✅ Use AbortController
+class Component extends HTMLElement {
+  controller: AbortController
+
+  constructor() {
+    super()
+    this.controller = new AbortController()
+  }
+
+  connectedCallback() {
+    const { signal } = this.controller
+    this.addEventListener("click", this.handler, { signal })
+  }
+
+  disconnectedCallback() {
+    this.controller.abort() // Removes all listeners
+  }
+}
+```
+
+### React hydration errors
+
+**Problem:** `Text content does not match server-rendered HTML`
+
+**Solution:**
+
+```tsx
+// Don't use client-only values on first render
+// ❌ Bad
+const Component = () => {
+  return <div>{window.innerWidth}</div>
+}
+
+// ✅ Good
+const Component = () => {
+  const [width, setWidth] = useState<number>()
+
+  useEffect(() => {
+    setWidth(window.innerWidth)
+  }, [])
+
+  return <div>{width ?? "Loading..."}</div>
+}
+```
+
+---
+
+## Performance Issues
+
+### Slow build times
+
+**Problem:** Build takes too long
+
+**Solutions:**
+
+```bash
+# 1. Clear cache
+rm -rf node_modules/.vite
+rm -rf dist
+
+# 2. Update dependencies
+pnpm update
+
+# 3. Use faster build
+pnpm build-vite  # Faster than full build
+
+# 4. Check for circular dependencies
+pnpm list --depth=0
+```
+
+### Large bundle size
+
+**Problem:** Bundle is too large
+
+**Solutions:**
+
+```typescript
+// 1. Use dynamic imports
+const Component = lazy(() => import('./Component'))
+
+// 2. Use IntersectionLoader
+IntersectionLoader.create('[data-lazy]', async () => {
+  const { default: Component } = await import('./Component')
+})
+
+// 3. Check bundle analysis
+pnpm build -- --analyze
+```
+
+---
+
+## Common Error Messages
+
+### "Cannot find module"
+
+```
+Error: Cannot find module '@pnx-mixtape/ids-shape'
+```
+
+**Fix:** `pnpm install`
+
+---
+
+### "The engine 'node' is incompatible"
+
+```
+error @pnx-mixtape/mxds@0.0.30: The engine "node" is incompatible
+```
+
+**Fix:** Install Node v20+
+
+---
+
+### "Type 'X' is not assignable to type 'Y'"
+
+```
+Type 'string | null' is not assignable to type 'string'
+```
+
+**Fix:** Add null check or use optional chaining
+
+---
+
+### "Cannot read property 'X' of null"
+
+```
+Cannot read property 'showPopover' of null
+```
+
+**Fix:** Check for null before accessing property
+
+---
+
+### "Expected class selector to be BEM"
+
+```
+Expected class selector to be BEM selector
+```
+
+**Fix:** Use BEM naming (block__element, block--modifier)
+
+---
+
+## Getting Help
+
+### Still stuck?
+
+1. **Search Issues:** https://github.com/previousnext/mxds/issues
+2. **Ask Question:** Create new issue with "question" label
+3. **Internal:** Ask in #mixtape Slack channel
+
+### Reporting Bugs
+
+Include:
+
+- Error message (full stack trace)
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment (Node version, OS, browser)
+- Code snippet (minimal reproduction)
+
+**Example:**
+
+```markdown
+## Bug Report
+
+**Error:**
+```
+
+Error: Cannot find module '@pnx-mixtape/ids-shape'
+
+```
+
+**Steps:**
+1. Clone repo
+2. Run `pnpm install`
+3. Run `pnpm dev`
+
+**Environment:**
+- Node: v20.10.0
+- pnpm: v9.0.0
+- OS: macOS 14.0
+
+**Expected:** Storybook starts
+**Actual:** Build fails with module not found
+```
+
+---
+
+## Related Documentation
+
+- [Contributing Guide](./Contributing.md)
+- [Testing Guide](./Testing.md)
+- [Component Architecture](./ComponentArchitecture.md)
+- [Memory Management](./MemoryManagement.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pnx-mixtape/mxds",
   "description": "The Mixtape Design System",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "license": "MIT",
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",
@@ -37,8 +37,8 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/node": "^26.0.0",
     "@vitejs/plugin-react": "^6.0.2",
-    "@vitest/browser-playwright": "4.1.11",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/browser-playwright": "4.1.12",
+    "@vitest/coverage-v8": "4.1.12",
     "chromatic": "^18.0.1",
     "concurrently": "^10.0.3",
     "cz-conventional-changelog": "^3.3.0",
@@ -46,7 +46,7 @@
     "drupal-twig-extensions": "1.0.0-beta.5",
     "jsdom": "^30.0.0",
     "lightningcss": "^1.32.0",
-    "oxfmt": "^0.71.0",
+    "oxfmt": "^0.74.0",
     "oxlint": "^1.71.0",
     "playwright": "^1.61.0",
     "postcss": "^8.5.15",
@@ -63,7 +63,7 @@
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vite-plugin-twig-drupal": "^1.7.0",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "config": {
     "commitizen": {
@@ -80,7 +80,10 @@
     "dist/types",
     "src",
     ".storybook",
-    "tools"
+    "docs",
+    "tools",
+    ".claude/skills",
+    "DESIGN.md"
   ],
   "exports": {
     ".": {

package/src/Atom/Button/Button.tsx

@@ -40,7 +40,7 @@ const Button = ({
       {...props}
     >
       {iconStart && <Icon icon={iconStart} />}
-      {children}
+      <span className={iconOnly ? "sr-only" : null}>{children}</span>
       {iconEnd && <Icon icon={iconEnd} />}
     </button>
   )