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

package/docs/MemoryManagement.md

@@ -0,0 +1,598 @@
+# Memory Management Guide
+
+Prevent memory leaks in Web Components and React applications.
+
+## Table of Contents
+
+- [Why Memory Leaks Matter](#why-memory-leaks-matter)
+- [Event Listeners](#event-listeners)
+- [Observers](#observers)
+- [Timers](#timers)
+- [React Hooks](#react-hooks)
+- [Testing for Leaks](#testing-for-leaks)
+- [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Why Memory Leaks Matter
+
+Memory leaks occur when resources aren't cleaned up properly, causing:
+
+- **Increased memory usage** over time
+- **Degraded performance** as garbage collection struggles
+- **Browser crashes** in long-running applications
+- **Wasted CPU cycles** from zombie event listeners
+
+**In a design system**, memory leaks are especially critical because:
+
+- Components may be created/destroyed frequently
+- A leak in one component multiplies across all instances
+- Consumer applications may run for hours/days
+
+---
+
+## Event Listeners
+
+### The Problem
+
+```typescript
+// ❌ BAD - Memory leak
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    this.addEventListener("click", this.handleClick)
+    document.addEventListener("keydown", this.handleKeyDown)
+  }
+
+  // No disconnectedCallback = listeners never removed!
+}
+```
+
+**Result:** Every time a component is created and destroyed, listeners accumulate.
+
+### The Solution: AbortController
+
+```typescript
+// ✅ GOOD - Proper cleanup
+class MyComponent extends HTMLElement {
+  controller: AbortController
+
+  constructor() {
+    super()
+    this.controller = new AbortController()
+  }
+
+  connectedCallback() {
+    const { signal } = this.controller
+
+    // All listeners use the signal
+    this.addEventListener("click", this.handleClick, { signal })
+    document.addEventListener("keydown", this.handleKeyDown, { signal })
+    window.addEventListener("resize", this.handleResize, { signal })
+  }
+
+  disconnectedCallback() {
+    // One line removes ALL listeners
+    this.controller.abort()
+  }
+
+  handleClick = () => {
+    /* ... */
+  }
+  handleKeyDown = () => {
+    /* ... */
+  }
+  handleResize = () => {
+    /* ... */
+  }
+}
+```
+
+### Benefits of AbortController
+
+- ✅ **One line cleanup** - `controller.abort()` removes all listeners
+- ✅ **No manual tracking** - Don't need to remember each listener
+- ✅ **Type-safe** - TypeScript knows about the signal option
+- ✅ **Browser standard** - Supported in all modern browsers
+- ✅ **Impossible to forget** - One controller for all listeners
+
+### Pattern for React
+
+```typescript
+useEffect(() => {
+  const controller = new AbortController()
+  const { signal } = controller
+
+  element.addEventListener("click", handler, { signal })
+  element.addEventListener("focus", otherHandler, { signal })
+
+  return () => {
+    controller.abort() // Cleanup on unmount
+  }
+}, [dependencies])
+```
+
+---
+
+## Observers
+
+### The Problem
+
+```typescript
+// ❌ BAD - Observer never disconnected
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    // Lost reference - can't disconnect later
+    const observer = new IntersectionObserver(entries => {
+      // ...
+    })
+    observer.observe(this)
+  }
+}
+```
+
+**Result:** Observer keeps running even after component is removed.
+
+### The Solution: Store as Properties
+
+```typescript
+// ✅ GOOD - Store observers as properties
+class MyComponent extends HTMLElement {
+  iO: IntersectionObserver
+  rO: ResizeObserver
+  mO: MutationObserver
+
+  connectedCallback() {
+    // Store observers
+    this.iO = new IntersectionObserver(entries => {
+      entries.forEach(({ isIntersecting, target }) => {
+        if (isIntersecting) {
+          // Handle intersection
+        }
+      })
+    })
+    this.iO.observe(this)
+
+    this.rO = new ResizeObserver(entries => {
+      entries.forEach(({ contentBoxSize }) => {
+        // Handle resize
+      })
+    })
+    this.rO.observe(this)
+
+    this.mO = new MutationObserver(mutations => {
+      mutations.forEach(({ type }) => {
+        // Handle mutation
+      })
+    })
+    this.mO.observe(this, { childList: true })
+  }
+
+  disconnectedCallback() {
+    // Disconnect all observers
+    this.iO.disconnect()
+    this.rO.disconnect()
+    this.mO.disconnect()
+  }
+}
+```
+
+### Optional Observers
+
+If an observer might not exist, use optional chaining:
+
+```typescript
+connectedCallback() {
+  // Only create if needed
+  if (this.hasAttribute('observe-resize')) {
+    this.rO = new ResizeObserver(...)
+    this.rO.observe(this)
+  }
+}
+
+disconnectedCallback() {
+  // Safe cleanup even if not created
+  this.iO?.disconnect()
+  this.rO?.disconnect()
+  this.mO?.disconnect()
+}
+```
+
+### Pattern for React
+
+```typescript
+useEffect(() => {
+  const observer = new IntersectionObserver(entries => {
+    // Handle entries
+  })
+
+  observer.observe(elementRef.current)
+
+  return () => {
+    observer.disconnect() // Cleanup on unmount
+  }
+}, [])
+```
+
+---
+
+## Timers
+
+### The Problem
+
+```typescript
+// ❌ BAD - Timeout never cleared
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    // Lost reference - can't clear later
+    setTimeout(() => {
+      this.doSomething()
+    }, 1000)
+
+    setInterval(() => {
+      this.poll()
+    }, 5000) // Runs forever!
+  }
+}
+```
+
+**Result:** Timers keep firing even after component is destroyed.
+
+### The Solution: Store Timer IDs
+
+```typescript
+// ✅ GOOD - Store timer IDs
+class MyComponent extends HTMLElement {
+  timeout: ReturnType<typeof setTimeout>
+  interval: ReturnType<typeof setInterval>
+
+  connectedCallback() {
+    // Store timer IDs
+    this.timeout = setTimeout(() => {
+      this.doSomething()
+    }, 1000)
+
+    this.interval = setInterval(() => {
+      this.poll()
+    }, 5000)
+  }
+
+  disconnectedCallback() {
+    // Clear timers
+    clearTimeout(this.timeout)
+    clearInterval(this.interval)
+  }
+}
+```
+
+### Add Timeout Safety to setInterval
+
+Prevent infinite loops if a condition is never met:
+
+```typescript
+// ✅ GOOD - Has timeout safety
+interval: ReturnType<typeof setInterval>
+timeout: ReturnType<typeof setTimeout>
+
+connectedCallback() {
+  // Safety timeout: give up after 2 seconds
+  this.timeout = setTimeout(() => {
+    clearInterval(this.interval)
+    this.interval = null
+    console.warn('Timeout: condition never met')
+  }, 2000)
+
+  // Check condition every 5ms
+  this.interval = setInterval(() => {
+    if (this.checkCondition()) {
+      clearTimeout(this.timeout)
+      clearInterval(this.interval)
+      this.timeout = null
+      this.interval = null
+      // Success!
+    }
+  }, 5)
+}
+
+disconnectedCallback() {
+  clearTimeout(this.timeout)
+  clearInterval(this.interval)
+}
+```
+
+### Pattern for React
+
+```typescript
+useEffect(() => {
+  const timeout = setTimeout(() => {
+    doSomething()
+  }, 1000)
+
+  const interval = setInterval(() => {
+    poll()
+  }, 5000)
+
+  return () => {
+    clearTimeout(timeout)
+    clearInterval(interval)
+  }
+}, [])
+```
+
+---
+
+## React Hooks
+
+### The Problem
+
+```typescript
+// ❌ BAD - No cleanup
+useEffect(() => {
+  element.addEventListener('click', handler)
+  const observer = new ResizeObserver(...)
+  observer.observe(element)
+}, [])
+```
+
+**Result:** Listeners and observers persist after component unmounts.
+
+### The Solution: Return Cleanup Functions
+
+```typescript
+// ✅ GOOD - Proper cleanup
+useEffect(() => {
+  const controller = new AbortController()
+  element.addEventListener("click", handler, {
+    signal: controller.signal,
+  })
+
+  const observer = new ResizeObserver(entries => {
+    // Handle resize
+  })
+  observer.observe(element)
+
+  return () => {
+    controller.abort() // Remove listeners
+    observer.disconnect() // Disconnect observer
+  }
+}, [element])
+```
+
+### Separate Controllers per Effect
+
+Don't share AbortControllers across multiple effects:
+
+```typescript
+// ❌ BAD - Shared controller causes conflicts
+const Component = () => {
+  const controller = new AbortController() // Shared!
+
+  useEffect(() => {
+    element.addEventListener("click", handler, { signal: controller.signal })
+    return () => controller.abort() // Aborts controller
+  }, [])
+
+  useEffect(() => {
+    // Uses same signal - will be aborted by first effect!
+    element.addEventListener("focus", handler, { signal: controller.signal })
+    return () => controller.abort() // Tries to abort again
+  }, [])
+}
+
+// ✅ GOOD - Separate controller per effect
+const Component = () => {
+  useEffect(() => {
+    const controller = new AbortController() // Isolated
+    element.addEventListener("click", handler, { signal: controller.signal })
+    return () => controller.abort()
+  }, [])
+
+  useEffect(() => {
+    const controller = new AbortController() // Another isolated
+    element.addEventListener("focus", handler, { signal: controller.signal })
+    return () => controller.abort()
+  }, [])
+}
+```
+
+---
+
+## Testing for Leaks
+
+### Manual Testing
+
+```javascript
+// Test 1: Rapid create/destroy
+for (let i = 0; i < 100; i++) {
+  const component = document.createElement("mx-component")
+  document.body.append(component)
+  component.remove()
+}
+
+// Expected: No observers, listeners, or timers remaining
+```
+
+### Chrome DevTools
+
+1. **Performance Monitor**
+   - Show: Listeners, Nodes, JS Heap
+   - Create/destroy components
+   - Numbers should return to baseline
+
+2. **Memory Profiler**
+   - Take heap snapshot before
+   - Create 100 components
+   - Destroy all components
+   - Take heap snapshot after
+   - Compare: Detached DOM nodes should be 0
+
+3. **Performance Tab**
+   - Record timeline
+   - Create/destroy components
+   - Look for: Continuous timer fires, listener calls
+
+### Automated Testing
+
+```typescript
+describe("Component Memory Leaks", () => {
+  it("should clean up event listeners", () => {
+    const component = document.createElement("mx-component")
+    document.body.append(component)
+
+    // Mock addEventListener to track calls
+    const addSpy = jest.spyOn(component, "addEventListener")
+    const removeSpy = jest.spyOn(component, "removeEventListener")
+
+    // Trigger connectedCallback
+    component.connectedCallback()
+
+    const listenerCount = addSpy.mock.calls.length
+
+    // Trigger disconnectedCallback
+    component.disconnectedCallback()
+    component.remove()
+
+    // With AbortController, no removeEventListener calls needed
+    // Just verify controller.abort() was called
+    expect(component.controller).toBeDefined()
+  })
+})
+```
+
+---
+
+## Common Pitfalls
+
+### 1. Forgetting disconnectedCallback
+
+```typescript
+// ❌ BAD
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    // Setup...
+  }
+  // Missing disconnectedCallback!
+}
+
+// ✅ GOOD
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    // Setup...
+  }
+
+  disconnectedCallback() {
+    // Cleanup...
+  }
+}
+```
+
+### 2. Anonymous Functions
+
+```typescript
+// ❌ BAD - Can't remove later
+element.addEventListener("click", () => {
+  // Can't removeEventListener - anonymous function!
+})
+
+// ✅ GOOD - Use AbortController instead
+const controller = new AbortController()
+element.addEventListener(
+  "click",
+  () => {
+    // Can abort all listeners at once
+  },
+  { signal: controller.signal },
+)
+```
+
+### 3. Conditional Cleanup
+
+```typescript
+// ❌ BAD - Conditional cleanup can miss things
+disconnectedCallback() {
+  if (this.hasObserver) {
+    this.observer.disconnect()
+  }
+  // What if hasObserver is wrong?
+}
+
+// ✅ GOOD - Optional chaining handles it
+disconnectedCallback() {
+  this.observer?.disconnect()  // Safe even if undefined
+}
+```
+
+### 4. Nested Components
+
+```typescript
+// ❌ BAD - Parent doesn't clean up children
+class Parent extends HTMLElement {
+  connectedCallback() {
+    this.child = document.createElement("mx-child")
+    this.append(this.child)
+  }
+  // Child never removed!
+}
+
+// ✅ GOOD - Clean up children
+class Parent extends HTMLElement {
+  child: HTMLElement
+
+  connectedCallback() {
+    this.child = document.createElement("mx-child")
+    this.append(this.child)
+  }
+
+  disconnectedCallback() {
+    this.child?.remove() // Remove child
+  }
+}
+```
+
+### 5. Global References
+
+```typescript
+// ❌ BAD - Global reference never cleared
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    window.MyComponent = this // Leaked!
+  }
+}
+
+// ✅ GOOD - Clear global references
+class MyComponent extends HTMLElement {
+  connectedCallback() {
+    window.MyComponent = this
+  }
+
+  disconnectedCallback() {
+    if (window.MyComponent === this) {
+      window.MyComponent = undefined
+    }
+  }
+}
+```
+
+---
+
+## Checklist
+
+Before shipping a component, verify:
+
+- [ ] **AbortController** used for all event listeners
+- [ ] **disconnectedCallback** implemented
+- [ ] **Observers** stored as properties and disconnected
+- [ ] **Timers** stored and cleared
+- [ ] **Global references** cleaned up
+- [ ] **React effects** return cleanup functions
+- [ ] **Optional chaining** used for nullable cleanup
+- [ ] **Tested** with rapid create/destroy
+- [ ] **DevTools** confirms no leaks
+- [ ] **Documentation** includes cleanup notes
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Component Architecture](./ComponentArchitecture.md)
+- [Security Guidelines](./Security.md)

package/docs/Migrations.md

@@ -0,0 +1,6 @@
+# Migration Guideline
+
+This document provides guides for migrating between major versions of Mixtape. Each guide includes a checklist of steps to follow, as well as links to relevant documentation and resources.
+
+> [!NOTE]
+> This document is a work in progress. We will be adding migration guides for each major version as they are released. If you have any questions or need help with a migration, please reach out to the Mixtape team.

package/docs/README.md

@@ -0,0 +1,100 @@
+# Documentation
+
+Welcome to the Mixtape Design System documentation!
+
+## 📚 Documentation Structure
+
+### Getting Started
+
+- [Main README](../README.md) - Installation and basic usage
+- [Introduction](../src/Introduction.mdx) - Design system overview
+
+### Developer Guides
+
+- **[Code Quality Guidelines](./CodeQuality.md)** - Comprehensive coding standards
+- **[Component Architecture](./ComponentArchitecture.md)** - How to build components
+- **[Memory Management](./MemoryManagement.md)** - Prevent memory leaks
+- **[Security Guidelines](./Security.md)** - Security best practices
+- **[CSS Guidelines](./CSSGuidelines.md)** - Styling conventions
+- **[Testing Guide](./Testing.md)** - Testing strategies
+- **[Contributing Guide](./Contributing.md)** - How to contribute
+
+### Reference
+
+- **[API Documentation](./API.md)** - Utilities and helpers
+- **[Migration Guides](./Migrations.md)** - Version upgrade guides
+- **[Troubleshooting](./Troubleshooting.md)** - Common issues and solutions
+
+### Component Documentation
+
+- Component-specific docs are in each component's `README.md`
+- See [src/Atom/README.md](../src/Atom/README.md) for atoms
+- See individual component folders for detailed usage (work in progress)
+
+## 🎯 Quick Links
+
+### For New Developers
+
+1. Read the [Main README](../README.md)
+2. Review [Component Architecture](./ComponentArchitecture.md)
+3. Check [Code Quality Guidelines](./CodeQuality.md)
+4. Browse [Storybook](https://mxds.pnx.io)
+
+### For Contributors
+
+1. Read [Contributing Guide](./Contributing.md)
+2. Follow [Code Quality Guidelines](./CodeQuality.md)
+3. Run tests: `pnpm test`
+4. Submit PR with conventional commits
+
+### For Designers
+
+1. Browse [Storybook](https://mxds.pnx.io)
+2. Check [Design Tokens](../src/tokens.js)
+3. Review component READMEs for usage
+
+## 📖 External Resources
+
+- [Storybook](https://mxds.pnx.io) - Interactive component library
+- [GitHub Repository](https://github.com/previousnext/mxds)
+- [npm Package](https://www.npmjs.com/package/@pnx-mixtape/mxds)
+- [PreviousNext Website](https://www.previousnext.com.au/)
+
+## 🔄 Document Status
+
+| Document                 | Status      | Last Updated |
+| ------------------------ | ----------- | ------------ |
+| CodeQuality.md           | ✅ Complete | 2026-03-05   |
+| ComponentArchitecture.md | ✅ Complete | 2026-03-05   |
+| MemoryManagement.md      | ✅ Complete | 2026-02-26   |
+| Security.md              | ✅ Complete | 2026-02-26   |
+| CSSGuidelines.md         | ✅ Complete | 2026-03-05   |
+| Testing.md               | ✅ Complete | 2026-02-26   |
+| Contributing.md          | ✅ Complete | 2026-02-26   |
+| API.md                   | ✅ Complete | 2026-03-05   |
+| Troubleshooting.md       | ✅ Complete | 2026-02-26   |
+
+## 💡 Contributing to Documentation
+
+Found a typo or want to improve our docs? Please submit a PR!
+
+```bash
+# Clone the repo
+git clone https://github.com/previousnext/mxds.git
+
+# Create a branch
+git checkout -b docs/improve-something
+
+# Make your changes
+# ...
+
+# Commit with conventional commits
+pnpm commit
+
+# Push and create PR
+git push origin docs/improve-something
+```
+
+---
+
+**Need help?** Open an issue on [GitHub](https://github.com/previousnext/mxds/issues)