@shortround/mui

Material-UI themed components for ShortRound command palette library.

Installation

npm install @shortround/core @shortround/mui

Peer Dependencies:

npm install @mui/material @emotion/react @emotion/styled @mui/icons-material lucide-react

Quick Start

import { ShortRoundSidekick } from '@shortround/core';
import { MuiSidekickComponents, useMuiToast } from '@shortround/mui';

const intentions = [
  {
    id: 'search',
    title: 'Search Items',
    group: 'Actions',
    icon: 'search', // Uses Lucide React icons
    action: async (input) => {
      return { intentions: searchResults };
    }
  }
];

function App() {
  const { showToast, ToastProvider } = useMuiToast();

  return (
    <ToastProvider>
      <div>
        <h1>My App</h1>
        <ShortRoundSidekick 
          title="Command Palette"
          defaultIntentions={intentions}
          SidekickComponents={MuiSidekickComponents}
          showToast={showToast}
          installKeyboardShortcuts={true}
        />
      </div>
    </ToastProvider>
  );
}

Components

MuiSidekickComponents

Pre-built Material-UI components for the sidekick interface:

import { MuiSidekickComponents } from '@shortround/mui';

// Contains:
// - IntentionPalette.Item, Input, Group, Frame, NoMatches
// - Sidekick.ControlBar, Frame, Popover  
// - SidecarContent

Toast Integration

import { useMuiToast, MuiToastProvider } from '@shortround/mui';

function MyComponent() {
  const { showToast } = useMuiToast();
  
  // Use in intention actions
  const intention = {
    id: 'save',
    title: 'Save Item',
    action: async (input) => {
      // ... save logic
      return { 
        message: 'Item saved successfully!',
        shouldReset: true 
      };
    }
  };

  return (
    <MuiToastProvider>
      <ShortRoundSidekick 
        showToast={showToast}
        // ... other props
      />
    </MuiToastProvider>
  );
}

Theming

Custom Theme

@shortround/mui simply consumes whatever MUI theme is already present in your React tree.
This keeps things predictable—just customize the theme exactly the same way you would in any MUI-only project.

import { createTheme, ThemeProvider } from '@mui/material/styles';
import { ShortRoundSidekick } from '@shortround/core';
import { MuiSidekickComponents } from '@shortround/mui';

// Your application theme
const myTheme = createTheme({
  palette: {
    primary: { main: '#546570' },
  },
  spacing: 4,
  shape: { borderRadius: 4 }
});

function App() {
  return (
    <ThemeProvider theme={myTheme}>
      <ShortRoundSidekick
        title="Short Round"
        SidekickComponents={MuiSidekickComponents}
        // ...other props
      />
    </ThemeProvider>
  );
}

For a working reference see examples/todo-app/src/MuiApp.jsx.

Custom Components

You can replace individual components:

import { MuiSidekickComponents } from '@shortround/mui';
import { MyCustomInput } from './MyCustomInput';

const CustomComponents = {
  ...MuiSidekickComponents,
  IntentionPalette: {
    ...MuiSidekickComponents.IntentionPalette,
    Input: MyCustomInput,
  },
};

Icons

Icons use Lucide React by default. Supported icon names include:

• search, settings, user, home, back, cancel
• Any valid Lucide React icon name

Custom icon mapping:

// In your intention
{
  id: 'custom',
  title: 'Custom Action',
  icon: 'star', // Maps to Lucide's Star icon
  action: async () => ({ shouldReset: true })
}

Keyboard Shortcuts

The MUI components support keyboard shortcuts displayed in the interface:

{
  id: 'save',
  title: 'Save Document',
  shortcut: 'Cmd+S',
  action: async () => {
    // Save logic
    return { message: 'Document saved!' };
  }
}

Sidekick Drawer

The sidekick drawer shows additional content alongside the command palette:

const intention = {
  id: 'edit-item',
  title: 'Edit Item',
  action: async (input) => {
    return {
      sideEffects: {
        sidecarRenderer: () => (
          <div style={{ padding: '16px' }}>
            <h3>Edit Form</h3>
            <form>
              {/* Your form content */}
            </form>
          </div>
        )
      }
    };
  }
};

Validation

Show validation messages in the input:

{
  id: 'create-item',
  title: 'Create New Item',
  validate: (input) => {
    if (!input.trim()) {
      return { valid: false, message: 'Name is required' };
    }
    if (input.length < 3) {
      return { valid: false, message: 'Name must be at least 3 characters' };
    }
    return { valid: true };
  },
  action: async (input) => {
    // Create item logic
    return { message: `Created "${input}"`, shouldReset: true };
  }
}

Complete Example

See the todo-app example for a full implementation showing:

• Multiple intention workflows
• Form validation
• Sidekick drawer usage
• Toast notifications
• Custom theming

Other Packages

• @shortround/core - Core hooks and functionality
• See the GitHub repo for other package details and examples

License

MIT