docs(architecture): enhance component creation MDC rules with concision framework

- Added Concision-First Decision Framework to guide component creation - Included Rule of Three guardrail for when to extract components - Added practical PR language guidance for code reviews - Enhanced agent role to prefer concision where appropriate - Restored priority levels, cross-references, and version history - Updated examples to reflect successful NotificationSection refactor - Enhanced .cursor/rules/component-creation-ideals.mdc to v2.0.0 - Added comprehensive migration patterns and testing guidelines - Established architectural standards for future component development
2025-08-15 09:07:49 +00:00
parent d62178bca5
commit 7e5c16446f
1 changed files with 321 additions and 0 deletions
--- a/.cursor/rules/component-creation-ideals.mdc
+++ b/.cursor/rules/component-creation-ideals.mdc
@@ -0,0 +1,321 @@
+---
+alwaysApply: true
+version: "2.0.0"
+lastUpdated: "2025-08-15"
+priority: "critical"
+---
+# Component Creation Ideals — TimeSafari Architecture (Directive MDC, v2)
+
+> **Agent role**: Apply these rules when creating, refactoring, or reviewing Vue components (Vue 3 with **vue-facing-decorator**). Prioritize **self-contained** components that hydrate from and persist to **PlatformServiceMixin** settings. Minimize parent–child coupling and prop drilling. Prefer **concision** where a separate component would add more API surface than value.
+
+## 📚 Cross-References
+
+- **Migration Example**: See `src/components/NotificationSection.vue` for successful refactor implementation
+- **Parent Component**: See `src/views/AccountViewView.vue` for before/after comparison
+- **Settings Infrastructure**: See `src/utils/PlatformServiceMixin.ts` for available methods
+- **Related Rules**: See `.cursor/rules/` for other architectural guidelines
+
+## Golden Rules (Enforce)
+
+### Priority Levels
+- 🔴 **CRITICAL**: Must be followed - breaking these creates architectural problems
+- 🟡 **HIGH**: Strongly recommended - important for maintainability
+- 🟢 **MEDIUM**: Good practice - improves code quality
+
+1. **Self-Contained Components** 🔴 **CRITICAL**
+   - Do **not** require parent props for internal state or behavior.
+   - Hydrate on `mounted()` via `this.$accountSettings()`; persist with `this.$saveSettings()`.
+   - Encapsulate business logic inside the component; avoid delegating core logic to the parent.
+   - Prefer **computed** getters for derived values; avoid stored duplicates of derived state.
+
+2. **Settings-First Architecture** 🔴 **CRITICAL**
+   - Use `PlatformServiceMixin` for reading/writing settings. Do **not** introduce new state managers (Pinia, custom stores) unless the state is *truly global*.
+   - Prefer **fetch-on-mount** over passing values via props.
+
+3. **Single Responsibility** 🟡 **HIGH**
+   - Each component owns **one clear purpose** (UI + related logic + settings persistence). Avoid splitting UI/logic across multiple components unless reusability clearly benefits.
+
+4. **Internal State Lifecycle** 🟡 **HIGH**
+   - Pattern: **defaults → hydrate on mount → computed for derived → persist on change**.
+   - Handle hydration errors gracefully (keep safe defaults; surface actionable UI states as needed).
+
+5. **Minimal Props** 🔴 **CRITICAL**
+   - Props are for **pure configuration** (labels, limits, feature flags). Do not pass data that can be loaded internally.
+   - **Never** pass props that mirror settings values (e.g., `isRegistered`, `notifying*`). Load those from settings.
+
+6. **Communication & Events** 🟡 **HIGH**
+   - Children may emit events for *user interactions* (e.g., `submitted`, `closed`) but **not** to offload core logic to the parent.
+   - Do not emit events solely to persist settings; the child handles persistence.
+
+7. **Testing** 🟢 **MEDIUM**
+   - Unit tests mount components in isolation; mock `this.$accountSettings`/`this.$saveSettings`.
+   - Verify hydration on mount, persistence on mutation, and graceful failure on settings errors.
+
+---
+
+## Concision-First Decision Framework
+
+> **Goal:** Avoid unnecessary components when a concise script, composable, or helper suffices.
+
+**Prefer NOT making a component when:**
+- **One-off UI**: used in exactly one view, unlikely to repeat.
+- **Small scope**: ~≤100–150 LOC, ≤3 reactive fields, ≤2 handlers.
+- **Purely presentational** with trivial logic.
+- **Local invariants**: behavior depends entirely on the view’s context.
+- **Abstraction cost > benefit**: would create an anemic component with props mirroring parent state.
+- **Better fit as code reuse**: logic works as a **composable/service/helper** without introducing new UI.
+
+**Concise alternatives:**
+- **Composable**: `useFeature()` encapsulates settings I/O and state.
+- **Service/Module**: plain TS helpers for formatting/validation.
+- **Directive**: tiny DOM behaviors that don’t need a lifecycle boundary.
+
+**When to make a component (even without reuse yet):**
+- **Isolation boundary**: async side effects, permission prompts, or recoverable error states.
+- **Stateful widget**: internal settings persistence, media controls, complex a11y.
+- **Slots/composition**: needs flexible children or layout.
+- **Different change rate**: sub-tree churns independently of the parent.
+- **Testability/ownership**: clear, ownable surface that’s easier to unit-test in isolation.
+
+**Rule of Three (guardrail):**
+- 1st time: inline or composable.
+- 2nd time: consider shared abstraction.
+- 3rd time: extract a component.
+
+**PR language (use when choosing concision):**
+- “One-off, ~80 LOC, no expected reuse. A component would add an API surface with no consumer. Keeping it local reduces cognitive load. If we see a second usage, promote to a composable; third usage, a component.”
+- “Logic lives in `useX()` to keep the view concise without prop plumbing; settings stay via `PlatformServiceMixin`.”
+
+---
+
+## Anti-Patterns (Reject)
+
+- Props that duplicate internal/derivable state: `:is-registered`, `:notifying-*`, etc.
+- Child components that are **UI-only** while parents hold the business logic for that feature.
+- Introducing Pinia/custom stores for per-component state.
+- Emitting `update:*` events to push settings responsibilities to parents.
+- Scattering a feature across multiple micro-components without a clear reuse reason.
+- Using props for computed/derived values (e.g., `showAdvancedFeatures` as a prop).
+
+---
+
+## Quick Examples
+
+### ✅ DO (Self-Contained, Settings-First)
+
+```vue
+<!-- Parent renders with no props -->
+<NotificationSection />
+```
+
+```ts
+// NotificationSection.vue (vue-facing-decorator + PlatformServiceMixin)
+import { Component, Vue } from "vue-facing-decorator";
+import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
+
+@Component({
+  mixins: [PlatformServiceMixin],
+})
+export default class NotificationSection extends Vue {
+  private notifyingNewActivity: boolean = false;
+
+  async mounted(): Promise<void> {
+    await this.hydrateFromSettings();
+  }
+
+  private async hydrateFromSettings(): Promise<void> {
+    try {
+      const s = await this.$accountSettings();
+      this.notifyingNewActivity = !!s.notifyingNewActivityTime;
+    } catch (err) {
+      // Keep defaults; optionally surface a non-blocking UI notice
+    }
+  }
+
+  private async updateNotifying(state: boolean): Promise<void> {
+    await this.$saveSettings({ notifyingNewActivityTime: state ? Date.now() : null });
+    this.notifyingNewActivity = state;
+  }
+}
+```
+
+### ❌ DON'T (Prop-Driven Coupling)
+
+```vue
+<!-- Parent passes internal state down -->
+<NotificationSection 
+  :is-registered="isRegistered"
+  :notifying-new-activity="notifyingNewActivity"
+/>
+```
+
+```ts
+// Child receives props (anti-pattern)
+export default class NotificationSection extends Vue {
+  isRegistered: boolean = false;
+  notifyingNewActivity: boolean = false;
+}
+```
+
+---
+
+## Component Structure Template (Drop-In)
+
+```ts
+/**
+ * ComponentName.vue — Purpose
+ * Owns: UI + logic + settings persistence (PlatformServiceMixin).
+ */
+import { Component, Vue } from "vue-facing-decorator";
+import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
+import type { Router } from "vue-router";
+
+@Component({
+  components: {
+    // child components here
+  },
+  mixins: [PlatformServiceMixin], // Settings access
+})
+export default class ComponentName extends Vue {
+  // Internal state
+  private myState: boolean = false;
+  private myData: string = "";
+
+  // Derived
+  private get isEnabled(): boolean {
+    return this.myState && this.hasPermissions;
+  }
+
+  async mounted(): Promise<void> {
+    await this.hydrateFromSettings();
+  }
+
+  private async hydrateFromSettings(): Promise<void> {
+    try {
+      const s = await this.$accountSettings();
+      this.myState = !!s.mySetting;
+      this.myData = s.myData ?? "";
+    } catch (err) {
+      // keep defaults
+    }
+  }
+
+  private async updateState(v: boolean): Promise<void> {
+    await this.$saveSettings({ mySetting: v });
+    this.myState = v;
+  }
+
+  async handleUserAction(): Promise<void> {
+    await this.updateState(true);
+  }
+}
+```
+
+---
+
+## Migration Playbook (Props → Self-Contained)
+
+> **Agent, when you see a component receiving `@Prop()` values that mirror settings or internal state, apply this playbook.**
+
+1. **Detect Anti-Props**
+   - Flag props matching: `is*`, `has*`, `notifying*`, or mirroring settings keys.
+   - Search for parent usage of these props and events.
+
+2. **Inline State**
+   - Remove anti-props and `@Prop()` declarations.
+   - Add private fields for state inside the child.
+   - Add `mounted()` hydration and persistence helpers via `PlatformServiceMixin`.
+
+3. **Parent Simplification**
+   - Replace `<Child :foo="..." :bar="..." @update="..."/>` with `<Child />`.
+   - Delete now-unused local state, watchers, and computed values that existed only to feed the child.
+
+4. **Events**
+   - Keep only user-interaction events (e.g., `submitted`). Remove persistence/logic events that the child now owns.
+
+5. **Tests**
+   - Update unit tests to mount child in isolation; mock settings I/O.
+   - Verify: hydrate on mount, persist on change, safe fallback on error.
+
+---
+
+## When Exceptions Are Acceptable
+
+- **Truly Global State** across distant components → use Pinia/service *sparingly*.
+- **Reusable Form Inputs** → accept `value` prop and emit `input`/`update:modelValue`; keep validation/business logic internal.
+- **Configuration-Only Props** for labels, visual variants, or limits — not for state that can be fetched.
+
+---
+
+## Definition of Done (Checklist)
+
+- [ ] No props required for internal state or settings-backed values.
+- [ ] Uses `PlatformServiceMixin` for all settings I/O.
+- [ ] Hydrates on `mounted()`, persists on mutations.
+- [ ] Single-responsibility: UI + logic + persistence together.
+- [ ] Computed getters for derived state.
+- [ ] Unit tests mock settings and cover hydrate/persist/failure paths.
+- [ ] Parent components contain no leftover `notifying-*` or similar prop wiring.
+
+---
+
+## Testing Snippets
+
+```ts
+// Hydration on mount
+test("hydrates from settings on mount", async () => {
+  const wrap = mount(MyComponent);
+  await wrap.vm.$nextTick();
+  expect((wrap.vm as any).myState).toBe(true);
+});
+```
+
+```ts
+// Mock settings methods
+jest.spyOn(wrapper.vm as any, "$accountSettings").mockResolvedValue({ mySetting: true });
+jest.spyOn(wrapper.vm as any, "$saveSettings").mockResolvedValue(void 0);
+```
+
+```ts
+// Graceful failure
+test("handles settings load failure", async () => {
+  jest.spyOn(wrapper.vm as any, "$accountSettings").mockRejectedValue(new Error("DB Error"));
+  const wrap = mount(MyComponent);
+  await wrap.vm.$nextTick();
+  expect((wrap.vm as any).myState).toBe(false); // default
+});
+```
+
+---
+
+## Rationale (Short)
+
+- **Concision first where appropriate** → avoid unnecessary components and API surfaces.
+- **Reduced coupling** → portability and reuse when boundaries are justified.
+- **Maintainability** → changes localized to the owning component.
+- **Consistency** → one canonical path for settings-backed features.
+
+**Rule of thumb:** _Can this feature operate independently, and does a component materially improve isolation or testability?_ If not, keep it concise (inline or composable).
+
+---
+
+## 📝 Version History
+
+### v2.0.0 (2025-08-15)
+- **Major Enhancement**: Added Concision-First Decision Framework
+- **New**: Rule of Three guardrail for component extraction
+- **New**: PR language guidance for code reviews
+- **Enhanced**: Agent role includes concision preference
+- **Refined**: Anti-patterns and examples updated
+
+### v1.0.0 (2025-08-15)
+- Initial creation based on successful NotificationSection refactor
+- Established core architectural principles for self-contained components
+- Added comprehensive migration playbook and testing guidelines
+- Included practical examples and anti-pattern detection
+
+### Future Enhancements
+- Additional migration patterns for complex components
+- Integration with automated refactoring tools
+- Performance benchmarking guidelines
+- Advanced testing strategies for complex state management