@mars-stack/cli 0.2.0 → 0.2.2

package/template/.cursor/skills/add-command-palette/SKILL.md

@@ -0,0 +1,438 @@
+# Skill: Add Command Palette
+
+Set up a Cmd+K command palette with fuzzy search, action registry, and keyboard navigation in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add a command palette, Cmd+K menu, keyboard shortcuts, quick search, or a spotlight-like interface.
+
+## Prerequisites
+
+- MARS template app with React
+- A modal/dialog primitive available (or use the native `<dialog>` element)
+
+## Architecture
+
+The command palette consists of:
+1. **Keyboard shortcut listener** — `Cmd+K` (Mac) / `Ctrl+K` (Windows/Linux) opens the palette
+2. **Action registry** — centralized list of commands (navigation, theme toggle, user actions)
+3. **Fuzzy search** — filters actions as the user types
+4. **Command palette UI** — search input, results list, keyboard navigation
+5. **`cmdk` library** — recommended for accessible, production-quality implementation
+
+## Step 1: Install `cmdk`
+
+```bash
+yarn add cmdk
+```
+
+The `cmdk` library provides an unstyled, composable command palette component with built-in keyboard navigation, fuzzy search, and accessibility.
+
+## Step 2: Define the Action Registry
+
+```typescript
+// src/features/command-palette/actions.ts
+import type { ReactNode } from 'react';
+
+export interface CommandAction {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: ReactNode;
+  keywords?: string[];
+  shortcut?: string[];
+  section: string;
+  onSelect: () => void;
+}
+
+export function createNavigationActions(router: { push: (path: string) => void }): CommandAction[] {
+  return [
+    {
+      id: 'nav-dashboard',
+      label: 'Go to Dashboard',
+      keywords: ['home', 'overview'],
+      section: 'Navigation',
+      shortcut: ['G', 'D'],
+      onSelect: () => router.push('/dashboard'),
+    },
+    {
+      id: 'nav-settings',
+      label: 'Go to Settings',
+      keywords: ['preferences', 'account'],
+      section: 'Navigation',
+      shortcut: ['G', 'S'],
+      onSelect: () => router.push('/settings'),
+    },
+    {
+      id: 'nav-profile',
+      label: 'Go to Profile',
+      keywords: ['account', 'user'],
+      section: 'Navigation',
+      onSelect: () => router.push('/settings/profile'),
+    },
+    {
+      id: 'nav-blog',
+      label: 'Go to Blog',
+      keywords: ['posts', 'articles'],
+      section: 'Navigation',
+      onSelect: () => router.push('/blog'),
+    },
+  ];
+}
+
+export function createThemeActions(setTheme: (theme: string) => void): CommandAction[] {
+  return [
+    {
+      id: 'theme-light',
+      label: 'Switch to Light Mode',
+      keywords: ['theme', 'appearance'],
+      section: 'Theme',
+      onSelect: () => setTheme('light'),
+    },
+    {
+      id: 'theme-dark',
+      label: 'Switch to Dark Mode',
+      keywords: ['theme', 'appearance'],
+      section: 'Theme',
+      onSelect: () => setTheme('dark'),
+    },
+    {
+      id: 'theme-system',
+      label: 'Use System Theme',
+      keywords: ['theme', 'appearance', 'auto'],
+      section: 'Theme',
+      onSelect: () => setTheme('system'),
+    },
+  ];
+}
+
+export function createUserActions(callbacks: {
+  onLogout: () => void;
+  onCopyUserId?: () => void;
+}): CommandAction[] {
+  return [
+    {
+      id: 'user-logout',
+      label: 'Sign Out',
+      keywords: ['logout', 'sign out', 'exit'],
+      section: 'Account',
+      onSelect: callbacks.onLogout,
+    },
+    ...(callbacks.onCopyUserId
+      ? [
+          {
+            id: 'user-copy-id',
+            label: 'Copy User ID',
+            keywords: ['id', 'identifier'],
+            section: 'Account',
+            onSelect: callbacks.onCopyUserId,
+          },
+        ]
+      : []),
+  ];
+}
+```
+
+## Step 3: Command Palette Component
+
+```typescript
+// src/features/command-palette/components/CommandPalette.tsx
+'use client';
+
+import { Command } from 'cmdk';
+import { useEffect, useState, useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+import { createNavigationActions, createThemeActions, createUserActions, type CommandAction } from '../actions';
+
+export function CommandPalette() {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const router = useRouter();
+
+  useEffect(() => {
+    function handleKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      }
+
+      if (e.key === 'Escape') {
+        setOpen(false);
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, []);
+
+  const handleSelect = useCallback(
+    (action: CommandAction) => {
+      setOpen(false);
+      setSearch('');
+      action.onSelect();
+    },
+    [],
+  );
+
+  const navigationActions = createNavigationActions(router);
+  const themeActions = createThemeActions((theme) => {
+    localStorage.setItem('mars-theme', theme);
+    const isDark = theme === 'dark' || (theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+    document.documentElement.classList.toggle('dark', isDark);
+  });
+  const userActions = createUserActions({
+    onLogout: () => router.push('/api/auth/logout'),
+  });
+
+  const allActions = [...navigationActions, ...themeActions, ...userActions];
+  const sections = [...new Set(allActions.map((a) => a.section))];
+
+  if (!open) return null;
+
+  return (
+    <div className="fixed inset-0 z-50">
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0 bg-black/50 backdrop-blur-sm"
+        onClick={() => setOpen(false)}
+      />
+
+      {/* Palette */}
+      <div className="absolute left-1/2 top-[20%] w-full max-w-lg -translate-x-1/2">
+        <Command
+          className="overflow-hidden rounded-xl border border-border-primary bg-surface-primary shadow-2xl"
+          shouldFilter={true}
+        >
+          <div className="flex items-center border-b border-border-primary px-4">
+            <SearchIcon className="mr-2 h-4 w-4 shrink-0 text-content-tertiary" />
+            <Command.Input
+              value={search}
+              onValueChange={setSearch}
+              placeholder="Type a command or search..."
+              className="flex h-12 w-full bg-transparent text-content-primary placeholder:text-content-tertiary focus:outline-none"
+            />
+            <kbd className="ml-2 shrink-0 rounded border border-border-primary bg-surface-secondary px-1.5 py-0.5 text-xs text-content-tertiary">
+              ESC
+            </kbd>
+          </div>
+
+          <Command.List className="max-h-80 overflow-y-auto p-2">
+            <Command.Empty className="px-4 py-8 text-center text-sm text-content-tertiary">
+              No results found.
+            </Command.Empty>
+
+            {sections.map((section) => (
+              <Command.Group
+                key={section}
+                heading={section}
+                className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-content-tertiary"
+              >
+                {allActions
+                  .filter((a) => a.section === section)
+                  .map((action) => (
+                    <Command.Item
+                      key={action.id}
+                      value={`${action.label} ${action.keywords?.join(' ') || ''}`}
+                      onSelect={() => handleSelect(action)}
+                      className="flex cursor-pointer items-center gap-3 rounded-lg px-3 py-2.5 text-sm text-content-primary aria-selected:bg-surface-secondary"
+                    >
+                      {action.icon && (
+                        <span className="flex h-5 w-5 items-center justify-center text-content-tertiary">
+                          {action.icon}
+                        </span>
+                      )}
+                      <div className="flex-1">
+                        <span>{action.label}</span>
+                        {action.description && (
+                          <span className="ml-2 text-content-tertiary">{action.description}</span>
+                        )}
+                      </div>
+                      {action.shortcut && (
+                        <div className="flex items-center gap-1">
+                          {action.shortcut.map((key) => (
+                            <kbd
+                              key={key}
+                              className="rounded border border-border-primary bg-surface-secondary px-1.5 py-0.5 text-xs text-content-tertiary"
+                            >
+                              {key}
+                            </kbd>
+                          ))}
+                        </div>
+                      )}
+                    </Command.Item>
+                  ))}
+              </Command.Group>
+            ))}
+          </Command.List>
+
+          <div className="flex items-center justify-between border-t border-border-primary px-4 py-2 text-xs text-content-tertiary">
+            <span>Navigate with ↑↓ keys</span>
+            <span>Select with ↵</span>
+          </div>
+        </Command>
+      </div>
+    </div>
+  );
+}
+
+function SearchIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className={className}>
+      <path fillRule="evenodd" d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z" clipRule="evenodd" />
+    </svg>
+  );
+}
+```
+
+## Step 4: Recent Items Support
+
+```typescript
+// src/features/command-palette/recent.ts
+const RECENT_KEY = 'mars-command-palette-recent';
+const MAX_RECENT = 5;
+
+export function getRecentActions(): string[] {
+  if (typeof window === 'undefined') return [];
+  const stored = localStorage.getItem(RECENT_KEY);
+  return stored ? JSON.parse(stored) : [];
+}
+
+export function addRecentAction(actionId: string): void {
+  const recent = getRecentActions().filter((id) => id !== actionId);
+  recent.unshift(actionId);
+  localStorage.setItem(RECENT_KEY, JSON.stringify(recent.slice(0, MAX_RECENT)));
+}
+```
+
+Integrate into the `handleSelect` callback:
+
+```typescript
+const handleSelect = useCallback(
+  (action: CommandAction) => {
+    addRecentAction(action.id);
+    setOpen(false);
+    setSearch('');
+    action.onSelect();
+  },
+  [],
+);
+```
+
+Then render a "Recent" section at the top of the command list when the search is empty:
+
+```typescript
+{!search && recentIds.length > 0 && (
+  <Command.Group heading="Recent">
+    {recentIds
+      .map((id) => allActions.find((a) => a.id === id))
+      .filter(Boolean)
+      .map((action) => (
+        <Command.Item key={action!.id} /* ... */ />
+      ))}
+  </Command.Group>
+)}
+```
+
+## Step 5: Register Custom Actions
+
+Allow features to register their own commands:
+
+```typescript
+// src/features/command-palette/registry.ts
+import type { CommandAction } from './actions';
+
+const customActions: CommandAction[] = [];
+
+export function registerAction(action: CommandAction): void {
+  const exists = customActions.findIndex((a) => a.id === action.id);
+  if (exists >= 0) {
+    customActions[exists] = action;
+  } else {
+    customActions.push(action);
+  }
+}
+
+export function getCustomActions(): CommandAction[] {
+  return [...customActions];
+}
+```
+
+Use from any feature:
+
+```typescript
+import { registerAction } from '@/features/command-palette/registry';
+
+registerAction({
+  id: 'billing-upgrade',
+  label: 'Upgrade Plan',
+  keywords: ['billing', 'subscription', 'pro'],
+  section: 'Billing',
+  onSelect: () => router.push('/billing/upgrade'),
+});
+```
+
+## Step 6: Add to Root Layout
+
+```typescript
+// src/app/(protected)/layout.tsx
+import { CommandPalette } from '@/features/command-palette/components/CommandPalette';
+
+export default function ProtectedLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <CommandPalette />
+      {children}
+    </>
+  );
+}
+```
+
+## Step 7: Trigger Button (Optional)
+
+For discoverability, add a search bar that opens the palette:
+
+```typescript
+// src/features/command-palette/components/CommandTrigger.tsx
+'use client';
+
+export function CommandTrigger() {
+  return (
+    <button
+      onClick={() => document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', metaKey: true }))}
+      className="flex items-center gap-2 rounded-lg border border-border-primary bg-surface-secondary px-3 py-1.5 text-sm text-content-tertiary transition-colors hover:border-interactive-primary hover:text-content-secondary"
+    >
+      <SearchIcon className="h-4 w-4" />
+      <span>Search...</span>
+      <kbd className="rounded border border-border-primary bg-surface-primary px-1.5 py-0.5 text-xs">
+        ⌘K
+      </kbd>
+    </button>
+  );
+}
+```
+
+## Testing
+
+1. Press `Cmd+K` — verify the palette opens with focus in the search input.
+2. Type a query — verify results filter with fuzzy matching.
+3. Use arrow keys — verify keyboard navigation highlights items.
+4. Press Enter — verify the selected action executes and the palette closes.
+5. Press Escape — verify the palette closes.
+6. Click the backdrop — verify the palette closes.
+7. Select an action — verify it appears in "Recent" on the next open.
+8. Register a custom action — verify it appears in the palette.
+
+## Checklist
+
+- [ ] `cmdk` library installed
+- [ ] Keyboard shortcut (`Cmd+K` / `Ctrl+K`) opens and closes the palette
+- [ ] Action registry with navigation, theme, and user actions
+- [ ] Fuzzy search filters actions as user types
+- [ ] Keyboard navigation with arrow keys and Enter
+- [ ] Recent items tracked in `localStorage`
+- [ ] Action sections with headings
+- [ ] Keyboard shortcuts displayed on action items
+- [ ] Custom action registration via `registerAction`
+- [ ] Palette placed in protected layout
+- [ ] Uses semantic design tokens (no raw colors)
+- [ ] Accessible — focus management, aria labels, screen reader support via `cmdk`

package/template/.cursor/skills/add-component/SKILL.md

@@ -0,0 +1,158 @@
+# Skill: Add a UI Component
+
+Create a new React component following the MARS design system conventions.
+
+## When to Use
+
+Use this skill when the user asks to create a new UI component, button variant, form element, or reusable UI pattern.
+
+## Decision: Primitive, Pattern, or Feature Component?
+
+| Type | Location | Business Logic? | Example |
+|------|----------|----------------|---------|
+| Primitive | `@mars-stack/ui` (primitives) | No | Button, Input, Badge, Toggle |
+| Pattern | `@mars-stack/ui` (patterns) | No | Card, Modal, DataTable, Pagination |
+| Feature | `src/features/<name>/components/` | Yes | BillingCard, UserProfileEditor |
+
+## Design Token System
+
+MARS uses a three-layer token system defined in `src/styles/`. **Never use raw Tailwind colours** like `text-gray-900` or `bg-blue-500`. Always use semantic tokens.
+
+### Token Quick Reference
+
+**Surfaces** (backgrounds):
+- `bg-surface-background` -- page background
+- `bg-surface-card` -- card/panel backgrounds
+- `bg-surface-elevated` -- elevated elements (dropdowns, popovers)
+- `bg-surface-input` -- form input backgrounds
+- `bg-surface-overlay` -- modal/dialog backdrops
+
+**Text**:
+- `text-text-primary` -- main body text
+- `text-text-secondary` -- supporting text
+- `text-text-muted` -- placeholder, disabled text
+- `text-text-link` / `hover:text-text-link-hover` -- links
+- `text-text-on-brand` -- text on brand-coloured backgrounds
+- `text-text-error` / `text-text-success` / `text-text-warning` / `text-text-info`
+
+**Borders**:
+- `border-border-default` -- default borders
+- `border-border-input` -- form input borders
+- `border-border-focus` -- focus state borders
+- `border-border-error` -- error state borders
+- `border-border-divider` -- horizontal/vertical dividers
+
+**Brand / Interactive**:
+- `bg-brand-primary` / `hover:bg-brand-primary-hover` -- primary actions
+- `bg-ghost-hover` / `bg-ghost-active` -- ghost/subtle button states
+- `bg-danger-bg` / `hover:bg-danger-hover` -- destructive actions
+- `focus:ring-ring-focus` -- focus rings
+
+**Feedback**:
+- `bg-success-muted` / `bg-error-muted` / `bg-warning-muted` / `bg-info-muted` -- subtle feedback backgrounds
+
+## Primitive Component Template
+
+```typescript
+import { clsx } from 'clsx';
+import { type ComponentPropsWithoutRef, forwardRef } from 'react';
+
+export interface ToggleProps extends Omit<ComponentPropsWithoutRef<'button'>, 'onChange'> {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  label?: string;
+  size?: 'sm' | 'md';
+}
+
+export const Toggle = forwardRef<HTMLButtonElement, ToggleProps>(
+  ({ checked, onChange, label, size = 'md', className, disabled, ...rest }, ref) => {
+    const trackSize = size === 'sm' ? 'h-5 w-9' : 'h-6 w-11';
+    const thumbSize = size === 'sm' ? 'h-3.5 w-3.5' : 'h-4 w-4';
+    const thumbTranslate = size === 'sm' ? 'translate-x-4' : 'translate-x-5';
+
+    return (
+      <label className={clsx('inline-flex items-center gap-2', className)}>
+        <button
+          ref={ref}
+          role="switch"
+          type="button"
+          aria-checked={checked}
+          disabled={disabled}
+          onClick={() => onChange(!checked)}
+          className={clsx(
+            'relative inline-flex shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200',
+            trackSize,
+            checked ? 'bg-brand-primary' : 'bg-surface-active',
+            disabled && 'opacity-(--disabled-opacity) cursor-not-allowed',
+            'focus:outline-none focus:ring-2 focus:ring-ring-focus focus:ring-offset-2',
+          )}
+          {...rest}
+        >
+          <span
+            className={clsx(
+              'pointer-events-none inline-block transform rounded-full bg-white shadow-sm transition-transform duration-200',
+              thumbSize,
+              checked ? thumbTranslate : 'translate-x-0.5',
+            )}
+          />
+        </button>
+        {label && (
+          <span className={clsx('text-text-primary', size === 'sm' ? 'text-sm' : 'text-base')}>
+            {label}
+          </span>
+        )}
+      </label>
+    );
+  },
+);
+
+Toggle.displayName = 'Toggle';
+```
+
+### Key Conventions
+
+1. Use `forwardRef` for primitives that wrap native elements.
+2. Accept `className` prop for overrides, merge with `clsx`.
+3. Export named (never default).
+4. Support common variants via props (`size`, `variant`).
+5. Use semantic tokens for all colours.
+6. Include proper `aria-*` attributes for accessibility.
+
+### Input Adornments (leading/trailing overlay buttons)
+
+When adding overlay buttons inside an input (e.g. password visibility toggle):
+
+- Wrap the input in a `relative` container; position the button with `absolute top-0 right-0 bottom-0`.
+- Give the button explicit dimensions: `h-full w-10` (40px matches input `pr-10`).
+- Center the icon: `flex items-center justify-center p-0` (reset button padding to avoid misalignment).
+- Add `shrink-0` to the button and icon so flex does not distort them.
+- Reserve input padding: add `pr-10` to the input when the adornment is present.
+
+```tsx
+<div className="relative">
+  <input className={clsx(showPasswordToggle && 'pr-10')} ... />
+  {showPasswordToggle && (
+    <button
+      type="button"
+      className="absolute top-0 right-0 bottom-0 flex h-full w-10 shrink-0 items-center justify-center p-0 text-text-muted hover:text-text-secondary"
+    >
+      <svg className="h-4 w-4 shrink-0" ... />
+    </button>
+  )}
+</div>
+```
+
+## After Creating
+
+1. Add the export to the `@mars-stack/ui` package barrel file.
+2. Export both the component and its props type.
+
+## Checklist
+
+- [ ] Correct directory (primitive / pattern / feature)
+- [ ] All colours use semantic tokens (no raw Tailwind colours)
+- [ ] `className` prop accepted and merged with `clsx`
+- [ ] Proper TypeScript interface exported
+- [ ] Accessibility attributes included
+- [ ] Dark mode works automatically (via token system)
+- [ ] Added to barrel export