@idealyst/mcp-server 1.2.101 → 1.2.103

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   storageGuides,
   toolDefinitions,
   translateGuides
-} from "./chunk-SRNAGZJL.js";
+} from "./chunk-74TE7CY7.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -467,6 +467,48 @@ UnistylesRegistry
   });
 \`\`\`
 
+## useTheme Hook
+
+Access the current theme in your components with full TypeScript inference:
+
+\`\`\`typescript
+import { useTheme } from '@idealyst/theme';
+
+function MyComponent() {
+  const theme = useTheme();
+
+  return (
+    <View style={{ backgroundColor: theme.colors.surface.primary }}>
+      <Text style={{ color: theme.colors.text.primary }}>
+        Hello
+      </Text>
+    </View>
+  );
+}
+\`\`\`
+
+The hook returns the properly typed theme based on your registered theme type:
+
+\`\`\`typescript
+const theme = useTheme();
+
+// Access intent colors
+const primaryColor = theme.intents.primary.primary;
+const successLight = theme.intents.success.light;
+
+// Access sizes
+const buttonPadding = theme.sizes.button.md.paddingHorizontal;
+
+// Access radii
+const borderRadius = theme.radii.md;
+
+// Access surface colors
+const screenBg = theme.colors.surface.screen;
+
+// Access text colors
+const textColor = theme.colors.text.primary;
+\`\`\`
+
 ## Platform-Specific Styles
 
 \`\`\`typescript
@@ -804,12 +846,12 @@ import { View, Card, Text } from '@idealyst/components';
 ### Form Input Spacing
 
 \`\`\`tsx
-import { Input, Checkbox, View } from '@idealyst/components';
+import { TextInput, Checkbox, View } from '@idealyst/components';
 
 // Use margin to space form fields
 <View>
-  <Input placeholder="Email" marginVertical="sm" />
-  <Input placeholder="Password" marginVertical="sm" />
+  <TextInput placeholder="Email" marginVertical="sm" />
+  <TextInput placeholder="Password" marginVertical="sm" />
   <Checkbox label="Remember me" marginVertical="md" />
 </View>
 \`\`\`
@@ -2144,6 +2186,8 @@ type TabBarScreenOptions = {
 } & ScreenOptions;
 \`\`\`
 
+> **Nested navigators:** When a Stack is nested inside a Tab, the **stack's root route** still uses \`TabBarScreenOptions\` for its \`options\` (it needs tabBarIcon/tabBarLabel for the tab bar). Type it as \`options: TabBarScreenOptions\` on the stack wrapper route.
+
 Example:
 \`\`\`tsx
 {
@@ -2258,6 +2302,45 @@ Full paths are automatically computed:
 - \`/dashboard/reports\`
 - \`/settings\`
 
+## Adding a New Screen to an Existing App
+
+When adding a new screen to a scaffolded project, you must complete ALL three steps:
+
+### Step 1: Create the screen component
+\`\`\`tsx
+// packages/shared/src/screens/TodoListScreen.tsx
+import { View, Text } from '@idealyst/components';
+
+export function TodoListScreen() {
+  return <View padding="md"><Text typography="h5">Todo List</Text></View>;
+}
+\`\`\`
+
+### Step 2: Register in the route config
+\`\`\`tsx
+// In your AppRouter.ts or route configuration file
+import { TodoListScreen } from '../screens/TodoListScreen';
+
+const appRouter: RouteParam = {
+  path: "/",
+  type: 'navigator',
+  layout: 'stack',
+  routes: [
+    { path: "", type: 'screen', component: HomeScreen },
+    { path: "todos", type: 'screen', component: TodoListScreen }, // Add this
+  ]
+};
+\`\`\`
+
+### Step 3: Navigate to the new screen
+\`\`\`tsx
+// In any existing screen
+const { navigate } = useNavigator();
+<Button onPress={() => navigate({ path: '/todos' })}>View Todos</Button>
+\`\`\`
+
+> **CRITICAL:** A screen component that is NOT registered in the route config is unreachable. Writing a screen without adding it to routes is a common mistake.
+
 ## Best Practices
 
 1. **Use relative paths** for child routes
@@ -2528,7 +2611,7 @@ header={{
   height: 80,
   content: (
     <View style={{ flexDirection: 'row', justifyContent: 'space-between', padding: 16 }}>
-      <Text size="lg" weight="bold">Dashboard</Text>
+      <Text typography="h6" weight="bold">Dashboard</Text>
       <UserMenu />
     </View>
   )
@@ -2723,7 +2806,7 @@ export const DashboardLayout: React.FC<StackLayoutProps> = ({
             alignItems: 'center',
             padding: 16
           }}>
-            <Text size="xl" weight="bold">Dashboard</Text>
+            <Text typography="h5" weight="bold">Dashboard</Text>
             <View style={{ flexDirection: 'row', gap: 16 }}>
               <NotificationBell />
               <UserAvatar />
@@ -2868,15 +2951,21 @@ navigator.navigate({ path: '/new-location', replace: true });
 
 ## useParams Hook
 
-Access current route path parameters:
+Access current route path parameters. Returns \`Record<string, string>\`.
+
+> **WARNING:** \`useParams()\` does NOT accept generic type arguments. Do NOT write \`useParams<{ id: string }>()\` \u2014 this causes TS2558. Access params by key from the returned record instead.
 
 \`\`\`tsx
 import { useParams } from '@idealyst/navigation';
 
 function UserScreen() {
+  // CORRECT \u2014 no type argument
   const params = useParams();
   const userId = params.id;        // Path param from /user/:id
 
+  // WRONG \u2014 useParams does NOT accept generics
+  // const params = useParams<{ id: string }>();  // TS2558 error!
+
   return <Text>User ID: {userId}</Text>;
 }
 \`\`\`
@@ -3232,7 +3321,7 @@ const { canGoBack, goBack } = useNavigator();
 
 {canGoBack() && (
   <Button
-    icon="arrow-left"
+    leftIcon="arrow-left"
     onPress={goBack}
   >
     Back
@@ -3309,11 +3398,11 @@ import { NavigatorParam, NotFoundComponentProps } from '@idealyst/navigation';
 const NotFoundPage = ({ path, params }: NotFoundComponentProps) => (
   <Screen>
     <View style={{ alignItems: 'center', padding: 24 }}>
-      <Icon name="alert-circle" size={64} color="red" />
-      <Text size="xl">Page Not Found</Text>
+      <Icon name="alert-circle" size="xl" intent="danger" />
+      <Text typography="h5">Page Not Found</Text>
       <Text color="secondary">The path "{path}" doesn't exist.</Text>
       {params && Object.keys(params).length > 0 && (
-        <Text size="sm">Params: {JSON.stringify(params)}</Text>
+        <Text typography="caption">Params: {JSON.stringify(params)}</Text>
       )}
     </View>
   </Screen>
@@ -3352,7 +3441,7 @@ const NotFoundPage = ({ path, params }: NotFoundComponentProps) => {
   return (
     <Screen>
       <View style={{ padding: 16, gap: 24 }}>
-        <Text size="xl">404 - Page Not Found</Text>
+        <Text typography="h5">404 - Page Not Found</Text>
         <Text>Attempted: {path}</Text>
         {params?.id && <Text>User ID: {params.id}</Text>}
         <Button onPress={() => navigate({ path: '/', replace: true })}>
@@ -3418,7 +3507,7 @@ Each navigator can have its own 404 handling:
 const SettingsNotFound = ({ path }: NotFoundComponentProps) => (
   <Screen>
     <View style={{ alignItems: 'center' }}>
-      <Icon name="cog-off" size={48} color="orange" />
+      <Icon name="cog-off" size="lg" intent="warning" />
       <Text>Settings page not found: {path}</Text>
     </View>
   </Screen>
@@ -3510,17 +3599,17 @@ const GlobalNotFound = ({ path, params }: NotFoundComponentProps) => {
   return (
     <Screen>
       <View style={{ padding: 24, gap: 24, alignItems: 'center', flex: 1, justifyContent: 'center' }}>
-        <Icon name="alert-circle-outline" size={64} color="red" />
-        <Text size="xl" weight="bold">Page Not Found</Text>
+        <Icon name="alert-circle-outline" size="xl" intent="danger" />
+        <Text typography="h5" weight="bold">Page Not Found</Text>
         <Text color="secondary">The page you're looking for doesn't exist.</Text>
 
         <Card style={{ marginTop: 16, padding: 16 }}>
-          <Text size="sm" weight="semibold">Attempted path:</Text>
-          <Text size="sm" color="secondary">{path}</Text>
+          <Text typography="caption" weight="semibold">Attempted path:</Text>
+          <Text typography="caption" color="secondary">{path}</Text>
           {params && Object.keys(params).length > 0 && (
             <>
-              <Text size="sm" weight="semibold" style={{ marginTop: 8 }}>Params:</Text>
-              <Text size="sm" color="secondary">{JSON.stringify(params)}</Text>
+              <Text typography="caption" weight="semibold" style={{ marginTop: 8 }}>Params:</Text>
+              <Text typography="caption" color="secondary">{JSON.stringify(params)}</Text>
             </>
           )}
         </Card>
@@ -3539,9 +3628,9 @@ const AdminNotFound = ({ path }: NotFoundComponentProps) => {
 
   return (
     <Screen>
-      <View padding={16} style={{ alignItems: 'center' }}>
-        <Icon name="shield-off" size={48} color="orange" />
-        <Text size="lg">Admin page not found</Text>
+      <View padding="md" style={{ alignItems: 'center' }}>
+        <Icon name="shield-off" size="lg" intent="warning" />
+        <Text typography="h6">Admin page not found</Text>
         <Button
           type="outlined"
           size="sm"
@@ -3736,7 +3825,7 @@ export function StackLayout({ options, currentPath }: StackLayoutProps) {
           {/* Title - centered or left-aligned */}
           <View style={{ flex: 1 }}>
             {typeof options?.headerTitle === 'string' ? (
-              <Text variant="title">{options.headerTitle}</Text>
+              <Text typography="h6" weight="bold">{options.headerTitle}</Text>
             ) : (
               options?.headerTitle
             )}
@@ -3821,16 +3910,17 @@ export function TabLayout({ routes, currentPath }: TabLayoutProps) {
                 })}
                 {options?.tabBarBadge && (
                   <Badge
-                    count={options.tabBarBadge}
                     style={{ position: 'absolute', top: -4, right: -8 }}
-                  />
+                  >
+                    {options.tabBarBadge}
+                  </Badge>
                 )}
               </View>
 
               {/* Label */}
               {options?.tabBarLabel && (
                 <Text
-                  size="xs"
+                  typography="caption"
                   style={{
                     marginTop: 4,
                     color: isActive ? '#007AFF' : '#8E8E93',
@@ -3882,7 +3972,7 @@ export function DrawerLayout({ routes, currentPath, options }: StackLayoutProps)
       }}>
         {/* Logo/Header */}
         <View style={{ height: 56, justifyContent: 'center', paddingHorizontal: 16 }}>
-          {!isCollapsed && <Text variant="title">My App</Text>}
+          {!isCollapsed && <Text typography="h6" weight="bold">My App</Text>}
         </View>
 
         {/* Menu Items */}
@@ -3918,7 +4008,7 @@ export function DrawerLayout({ routes, currentPath, options }: StackLayoutProps)
           onPress={() => setIsCollapsed(!isCollapsed)}
           style={{ padding: 12, marginTop: 'auto' }}
         >
-          <Icon name={isCollapsed ? 'chevron-right' : 'chevron-left'} size={24} />
+          <Icon name={isCollapsed ? 'chevron-right' : 'chevron-left'} size="sm" />
         </Pressable>
       </View>
 
@@ -3946,7 +4036,7 @@ export function AppLayout({ options, routes, currentPath, children }: StackLayou
         height: 56,
         content: (
           <View style={{ flexDirection: 'row', alignItems: 'center', flex: 1 }}>
-            <Text variant="title">{options?.headerTitle || 'App'}</Text>
+            <Text typography="h6" weight="bold">{options?.headerTitle || 'App'}</Text>
             <View style={{ marginLeft: 'auto' }}>{options?.headerRight}</View>
           </View>
         ),
@@ -4091,15 +4181,59 @@ Idealyst uses Material Design Icons (@mdi/react) with **7,447 icons** available.
 
 ## Icon Usage
 
-### In Components
+### TypeScript Type \u2014 CRITICAL
+
+Icon names are typed as \`IconName\`, NOT \`string\`. Use **bare names** like \`'home'\`, \`'check-circle'\` \u2014 do NOT add an \`'mdi:'\` prefix.
 
-Icons can be used by providing the icon name as a string:
+When you create helper functions that return icon names, you MUST type them as \`IconName\`:
+
+\`\`\`tsx
+import type { IconName } from '@idealyst/components';
+
+// CORRECT: return type is IconName
+function getStatusIcon(status: string): IconName {
+  switch (status) {
+    case 'active': return 'check-circle';
+    case 'pending': return 'clock-outline';
+    default: return 'help-circle';
+  }
+}
+
+// WRONG: return type 'string' will cause TS2322 error when passed to icon props
+// function getStatusIcon(status: string): string { ... }  // \u274C
+
+// For icon lookup maps, type the values as IconName:
+const FILE_TYPE_ICONS: Record<string, IconName> = {
+  'image': 'file-image',
+  'video': 'file-video',
+  'audio': 'file-music',
+  'document': 'file-document',
+  'default': 'file',
+};
+
+function getFileIcon(type: string): IconName {
+  return FILE_TYPE_ICONS[type] ?? FILE_TYPE_ICONS['default'];
+}
+\`\`\`
+
+### When to Import \`Icon\` vs Use \`IconName\` Type
+
+- Import the \`Icon\` component only when rendering a standalone icon as JSX: \`<Icon name="home" />\`
+- For component props like \`leftIcon\` on Button, \`leading\`/\`trailing\` on ListItem \u2014 pass bare string names. Do NOT import the \`Icon\` component for this use.
+- Import ONLY the \`IconName\` type (not the component) when you need a typed variable for an icon name:
+
+\`\`\`tsx
+import type { IconName } from '@idealyst/components';
+const myIcon: IconName = 'home';  // Correct: type-only import
+\`\`\`
+
+### In Components
 
 \`\`\`tsx
 import { Button, Icon, List, Badge } from '@idealyst/components';
 
-// Button with icon
-<Button icon="check">Save</Button>
+// Button with icon (use leftIcon, NOT icon)
+<Button leftIcon="check">Save</Button>
 
 // Standalone Icon
 <Icon name="home" size="md" color="primary" />
@@ -4115,7 +4249,7 @@ import { Button, Icon, List, Badge } from '@idealyst/components';
 
 \`\`\`tsx
 <Icon
-  name="home"                    // Icon name (required)
+  name="home"                    // Icon name (required) \u2014 type: IconName
   size="xs|sm|md|lg|xl|number"   // Icon size
   color="primary|secondary|..."   // Theme color
 />
@@ -4340,11 +4474,12 @@ Icons follow naming patterns:
 
 ### Button Icons
 \`\`\`tsx
-<Button icon="content-save">Save</Button>
-<Button icon="delete" intent="danger">Delete</Button>
-<Button icon="pencil">Edit</Button>
-<Button icon="plus">Add New</Button>
+<Button leftIcon="content-save">Save</Button>
+<Button leftIcon="delete" intent="danger">Delete</Button>
+<Button leftIcon="pencil">Edit</Button>
+<Button leftIcon="plus">Add New</Button>
 \`\`\`
+> **Note:** Button uses \`leftIcon\` and \`rightIcon\` \u2014 NOT \`icon\`.
 
 ### List Icons
 \`\`\`tsx
@@ -4356,9 +4491,9 @@ Icons follow naming patterns:
 
 ### Navigation Icons
 \`\`\`tsx
-<Button icon="arrow-left" variant="text">Back</Button>
-<Button icon="menu" variant="text">Menu</Button>
-<Button icon="close" variant="text">Close</Button>
+<Button leftIcon="arrow-left" type="text">Back</Button>
+<Button leftIcon="menu" type="text">Menu</Button>
+<Button leftIcon="close" type="text">Close</Button>
 \`\`\`
 
 ### Status Icons