create-asciitorium 0.1.45 → 0.1.47

package/dist/templates/base/ASCIITORIUM_REFERENCE.md

@@ -1,6 +1,8 @@
 # ASCIITORIUM Quick Reference
 
-> **For LLMs**: This document provides correct usage patterns for ASCIITORIUM components. Always refer to the examples here rather than assuming React-like conventions.
+> **For LLMs**: This document provides correct usage patterns for ASCIITORIUM
+> components. Always refer to the examples here rather than assuming React-like
+> conventions.
 
 ## Quick Index
 
@@ -35,7 +37,7 @@
 - [Keybind](#keybind)
 - [PerfMonitor](#perfmonitor)
 
----
+
 
 ## State Management
 
@@ -118,7 +120,7 @@ count++; // NO! count is a State object
 count.value++;
 ```
 
----
+
 
 ## JSX & Props
 
@@ -172,7 +174,7 @@ align="center"                 // Alignment (layout-specific)
 </Text>
 ```
 
----
+
 
 ## Row
 
@@ -215,7 +217,7 @@ align="center"                 // Alignment (layout-specific)
 </Row>
 ```
 
----
+
 
 ## Column
 
@@ -244,7 +246,7 @@ align="center"                 // Alignment (layout-specific)
 
 ```tsx
 <Column align="center" width="100%" gap={2}>
-  <Art src="logo" />
+  <Art sprite="logo" />
   <Text>Welcome</Text>
   <Button>Start</Button>
 </Column>
@@ -262,7 +264,7 @@ align="center"                 // Alignment (layout-specific)
 </Column>
 ```
 
----
+
 
 ## Text
 
@@ -361,7 +363,7 @@ const playerName = new State('Hero');
 <Text>{count.value}</Text>     // Explicit .value also works
 ```
 
----
+
 
 ## Button
 
@@ -439,7 +441,7 @@ const count = new State(0);
 <Button>Very Long Text</Button> // Auto-sizes
 ```
 
----
+
 
 ## Select
 
@@ -553,142 +555,170 @@ const selected = new State("option1");
 </Select>
 ```
 
----
+
 
 ## Switch
 
 ### Basic Usage
 
 ```tsx
-import { State, Switch } from 'asciitorium';
+import { State, Switch, Case, Default } from 'asciitorium';
 
-// State holding the component to display
-const currentView = new State<any>(DashboardComponent);
+const userRole = new State<string>('guest');
 
-<Switch component={currentView} />;
+<Switch condition={userRole}>
+  <Case when="admin" create={AdminPanel} />
+  <Case when="user" create={UserPanel} />
+  <Case when="guest" create={GuestPanel} />
+  <Default create={GuestPanel} />
+</Switch>;
 ```
 
-### Props
+### Props (Switch)
+
+| Prop        | Type                             | Default | Description                        |
+| ----------- | -------------------------------- | ------- | ---------------------------------- |
+| `condition` | `State<string> \| State<number>` | -       | State to match against Case values |
+| `width`     | `number \| 'fill'`               | -       | Component width                    |
+| `height`    | `number \| 'fill'`               | -       | Component height                   |
+
+### Props (Case)
+
+| Prop     | Type               | Description                         |
+| -------- | ------------------ | ----------------------------------- |
+| `when`   | `string \| number` | Value to match against condition    |
+| `create` | `any`              | Component class/function to create  |
+| `with`   | `any`              | Optional props to pass to component |
 
-| Prop        | Type                                                             | Default | Description                                               |
-| ----------- | ---------------------------------------------------------------- | ------- | --------------------------------------------------------- |
-| `component` | `State<Component \| (() => Component) \| (new () => Component)>` | -       | State holding component instance, constructor, or factory |
-| `width`     | `number \| 'fill'`                                               | -       | Component width                                           |
-| `height`    | `number \| 'fill'`                                               | -       | Component height                                          |
+### Props (Default)
+
+| Prop     | Type  | Description                         |
+| -------- | ----- | ----------------------------------- |
+| `create` | `any` | Component class/function to create  |
+| `with`   | `any` | Optional props to pass to component |
 
 ### Common Patterns
 
-**Pattern 1: View Switching**
+**Pattern 1: Simple Conditional Rendering**
 
 ```tsx
-import { State, Switch, Button, Column } from 'asciitorium';
+import { State, Switch, Case, Default } from 'asciitorium';
 
-// Component classes/constructors
-class DashboardView extends Component {
-  /* ... */
-}
-class SettingsView extends Component {
-  /* ... */
-}
-class ProfileView extends Component {
-  /* ... */
-}
+// Function components
+const AdminPanel = () => <Column>Admin View</Column>;
+const UserPanel = () => <Column>User View</Column>;
+const GuestPanel = () => <Column>Guest View</Column>;
 
-const currentView = new State<any>(DashboardView);
+const userRole = new State<string>('guest');
 
 <Column>
-  <Button onClick={() => (currentView.value = DashboardView)}>Dashboard</Button>
-  <Button onClick={() => (currentView.value = SettingsView)}>Settings</Button>
-  <Button onClick={() => (currentView.value = ProfileView)}>Profile</Button>
-
-  <Switch component={currentView} width="fill" height="fill" />
+  <Button onClick={() => (userRole.value = 'admin')}>Admin</Button>
+  <Button onClick={() => (userRole.value = 'user')}>User</Button>
+  <Button onClick={() => (userRole.value = 'guest')}>Guest</Button>
+
+  <Switch condition={userRole} width="fill" height="fill">
+    <Case when="admin" create={AdminPanel} />
+    <Case when="user" create={UserPanel} />
+    <Case when="guest" create={GuestPanel} />
+    <Default create={GuestPanel} />
+  </Switch>
 </Column>;
 ```
 
-**Pattern 2: Dynamic Content with Select**
+**Pattern 2: Class Components with Props**
 
 ```tsx
-import { State, Select, Option, Switch } from 'asciitorium';
+import { State, Switch, Case, Component } from 'asciitorium';
 
-// Component map
-const pageMap: Record<string, any> = {
-  home: HomeComponent,
-  about: AboutComponent,
-  contact: ContactComponent,
-};
+class SettingsPanel extends Component {
+  constructor(props: { theme: string }) {
+    super(props);
+    // Use props.theme
+  }
+}
 
-const selectedKey = new State<string>('home');
-const selectedComponent = new State<any>(pageMap['home']);
+const currentView = new State<string>('settings');
 
-// Sync selected component with key
-selectedKey.subscribe((key) => {
-  selectedComponent.value = pageMap[key];
-});
+<Switch condition={currentView}>
+  <Case when="settings" create={SettingsPanel} with={{ theme: 'dark' }} />
+  <Case when="profile" create={ProfilePanel} />
+</Switch>;
+```
+
+**Pattern 3: Navigation with Select**
+
+```tsx
+import { State, Select, Option, Switch, Case } from 'asciitorium';
+
+const selectedPage = new State<string>('home');
 
 <Column>
-  <Select selected={selectedKey}>
+  <Select selected={selectedPage}>
     <Option value="home" label="Home" />
     <Option value="about" label="About" />
     <Option value="contact" label="Contact" />
   </Select>
 
-  <Switch component={selectedComponent} width="fill" height="fill" />
+  <Switch condition={selectedPage} width="fill" height="fill">
+    <Case when="home" create={HomePage} />
+    <Case when="about" create={AboutPage} />
+    <Case when="contact" create={ContactPage} />
+  </Switch>
 </Column>;
 ```
 
-**Pattern 3: Factory Functions**
-
-```tsx
-// Using factory functions instead of constructors
-const viewFactory = () => new CustomView({ customProp: 'value' });
-const currentView = new State<any>(viewFactory);
-
-<Switch component={currentView} />;
-```
-
-**Pattern 4: Component Instances**
+**Pattern 4: Numeric Conditions**
 
 ```tsx
-// Using pre-instantiated components
-const dashboard = new DashboardView({ width: 80 });
-const settings = new SettingsView({ width: 80 });
-
-const currentView = new State<Component>(dashboard);
+const level = new State<number>(1);
 
-<Button onClick={() => currentView.value = settings}>Switch to Settings</Button>
-<Switch component={currentView} />
+<Switch condition={level}>
+  <Case when={1} create={Level1} />
+  <Case when={2} create={Level2} />
+  <Case when={3} create={Level3} />
+  <Default create={CompletionScreen} />
+</Switch>;
 ```
 
 ### Common Mistakes
 
-❌ **WRONG** - Not using State
+❌ **WRONG** - Using JSX children
 
 ```tsx
-<Switch component={MyComponent} /> // NO! component must be a State
+<Switch condition={role}>
+  <Case when="admin">
+    <AdminPanel /> {/* Components persist in memory! */}
+  </Case>
+</Switch>
 ```
 
-✅ **CORRECT** - Using State
+✅ **CORRECT** - Using create prop
 
 ```tsx
-const view = new State(MyComponent);
-<Switch component={view} />;
+<Switch condition={role}>
+  <Case when="admin" create={AdminPanel} />
+</Switch>
 ```
 
-❌ **WRONG** - Trying to pass component as string
+❌ **WRONG** - Missing Default fallback
 
 ```tsx
-const view = new State<string>('DashboardComponent'); // NO! Must be actual component
-<Switch component={view} />;
+<Switch condition={status}>
+  <Case when="loading" create={Spinner} />
+  {/* No fallback - nothing shows if status is unknown */}
+</Switch>
 ```
 
-✅ **CORRECT** - Using actual component reference
+✅ **CORRECT** - Including Default
 
 ```tsx
-const view = new State<any>(DashboardComponent); // Component constructor
-<Switch component={view} />;
+<Switch condition={status}>
+  <Case when="loading" create={Spinner} />
+  <Default create={ErrorMessage} />
+</Switch>
 ```
 
----
+
 
 ## TextInput
 
@@ -771,73 +801,88 @@ const text = new State('initial');
 <Button onClick={() => console.log(inputValue.value)}>Submit</Button>
 ```
 
----
+
 
 ## Art
 
 ### Basic Usage
 
 ```tsx
-// Load from file
-<Art src="logo" />
-
-// ASCII art from figlet font
-<Art font="standard" text="Hello" />
+// Load sprite from file
+<Art sprite="logo" />
 
 // Align center
-<Art src="banner" align="center" />
+<Art sprite="banner" align="center" />
 ```
 
 ### Props
 
-| Prop     | Type                            | Default  | Description                      |
-| -------- | ------------------------------- | -------- | -------------------------------- |
-| `src`    | `string`                        | -        | Art file name (from art/ folder) |
-| `font`   | `string`                        | -        | Figlet font name                 |
-| `text`   | `string`                        | -        | Text to render with font         |
-| `width`  | `number \| 'auto'`              | `'auto'` | Component width                  |
-| `height` | `number \| 'auto'`              | `'auto'` | Component height                 |
-| `align`  | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment             |
-| `border` | `boolean`                       | `false`  | Show border                      |
+| Prop     | Type                            | Default  | Description                          |
+| -------- | ------------------------------- | -------- | ------------------------------------ |
+| `sprite` | `string`                        | -        | Sprite file name (from art/sprites/) |
+| `width`  | `number \| 'auto'`              | `'auto'` | Component width                      |
+| `height` | `number \| 'auto'`              | `'auto'` | Component height                     |
+| `align`  | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment                 |
+| `border` | `boolean`                       | `false`  | Show border                          |
 
 ### Common Patterns
 
-**Pattern 1: Logo from File**
+**Pattern 1: Static Sprite**
 
 ```tsx
-// Loads from art/logo.art
-<Art src="logo" align="center" />
+// Loads from art/sprites/logo.art
+<Art sprite="logo" align="center" />
 ```
 
-**Pattern 2: Generated ASCII Text**
+**Pattern 2: Animated Sprite**
 
 ```tsx
-<Art font="standard" text="Game Over" align="center" />
+// Loads animated art (auto-plays)
+<Art sprite="beating-heart" width={20} />
 ```
 
-**Pattern 3: Animated Sprite**
+
+
+## Banner
+
+### Basic Usage
 
 ```tsx
-// Loads animated art (auto-plays)
-<Art src="beating-heart" width={20} />
+// Render text with font
+<Banner font="standard" text="Hello" />
+
+// Align center
+<Banner font="shadows" text="Game Over" align="center" />
 ```
 
-### Common Mistakes
+### Props
 
-❌ **WRONG** - Using both src and font
+| Prop            | Type                            | Default  | Description                       |
+| --------------- | ------------------------------- | -------- | --------------------------------- |
+| `font`          | `string`                        | -        | Font name (from art/fonts/)       |
+| `text`          | `string \| State<string>`       | -        | Text to render with font          |
+| `letterSpacing` | `number`                        | `0`      | Additional spacing between chars  |
+| `width`         | `number \| 'auto'`              | `'auto'` | Component width                   |
+| `height`        | `number \| 'auto'`              | `'auto'` | Component height                  |
+| `align`         | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment              |
+| `border`        | `boolean`                       | `false`  | Show border                       |
+
+### Common Patterns
+
+**Pattern 1: Title Screen**
 
 ```tsx
-<Art src="logo" font="standard" /> // Conflicting props
+<Banner font="shadows" text="asciitorium" align="center" />
 ```
 
-✅ **CORRECT** - Use one or the other
+**Pattern 2: Reactive Text**
 
 ```tsx
-<Art src="logo" />        // From file
-<Art font="standard" text="Title" />  // Generated
+const score = new State(0);
+<Banner font="pixel" text={score} letterSpacing={1} />
 ```
 
----
+
 
 ## Keybind
 
@@ -926,7 +971,7 @@ const gameStarted = new State(false);
 <Keybind keyBinding="ArrowUp" action={() => moveUp()} />
 ```
 
----
+
 
 ## GameWorld
 
@@ -1055,7 +1100,7 @@ gameWorld.player.value.x += 1; // Bypasses collision detection
 gameWorld.moveForward(); // Handles collision
 ```
 
----
+
 
 ## MapView
 
@@ -1138,7 +1183,7 @@ gameWorld.player.subscribe((p) => {
 <MapView mapAsset={gameWorld.mapAsset} player={gameWorld.player} />
 ```
 
----
+
 
 ## FirstPersonView
 
@@ -1216,7 +1261,7 @@ gameWorld.player.subscribe((p) => {
 <FirstPersonView mapAsset={gameWorld.mapAsset} player={gameWorld.player} />
 ```
 
----
+
 
 ## PerfMonitor
 
@@ -1267,7 +1312,7 @@ const showPerf = new State(false);
 <PerfMonitor visible={showPerf} />
 ```
 
----
+
 
 ## Component Lifecycle
 
@@ -1307,7 +1352,7 @@ count.subscribe((newValue) => {
 // No manual cleanup needed in most cases
 ```
 
----
+
 
 ## Legend System (Game Maps)
 
@@ -1368,7 +1413,7 @@ if (tile?.tag === 'door') {
 }
 ```
 
----
+
 
 ## Directory Structure
 
@@ -1409,7 +1454,7 @@ Example:
 ╚══════════════════╝
 ```
 
----
+
 
 ## Type Annotations
 
@@ -1451,7 +1496,7 @@ const entry: LegendEntry = {
 };
 ```
 
----
+
 
 ## Complete Example: Simple Game
 
@@ -1522,28 +1567,32 @@ const app = (
 await app.start();
 ```
 
----
+
 
 ## Understanding "auto" vs Omitting Props
 
-**Key Concept:** In ASCIITORIUM, omitting `width` or `height` props is the same as setting them to `undefined` or `"auto"`.
+**Key Concept:** In ASCIITORIUM, omitting `width` or `height` props is the same
+as setting them to `undefined` or `"auto"`.
 
 - `width={40}` → Fixed width of 40 characters
 - `width="fill"` → Fill available parent space
 - `width="auto"` → Auto-size to content (same as omitting the prop)
 - _Omitting width prop_ → Auto-size to content (recommended approach)
 
-**Recommendation:** Omit props instead of using `"auto"` for clarity. The type system allows `"auto"` but it's unnecessary.
+**Recommendation:** Omit props instead of using `"auto"` for clarity. The type
+system allows `"auto"` but it's unnecessary.
 
 **Component-specific auto-sizing:**
 
-- **Text**: Auto-sizes to content length (width) and wrapped lines (height) when props omitted
-- **Button**: Always calculates size based on content (`buttonText.length + 7` for width, `4` for height)
+- **Text**: Auto-sizes to content length (width) and wrapped lines (height) when
+  props omitted
+- **Button**: Always calculates size based on content (`buttonText.length + 7`
+  for width, `4` for height)
 - **Art**: Auto-sizes to loaded art dimensions when props omitted
 - **Column**: Auto-sizes to fit children when width omitted
 - **Row**: Defaults to `width="fill"`
 
----
+
 
 ## Tips for LLMs
 
@@ -1552,12 +1601,16 @@ await app.start();
 3. **Text newlines use `¶` (pilcrow)** - Not `\n`
 4. **Components accept children via JSX or explicit props** - Both patterns work
 5. **GameWorld must be awaited** - `await gameWorld.ready` before rendering
-6. **Keybinds are invisible components** - They never render, just register handlers
-7. **MapView and FirstPersonView are display-only** - Movement logic goes in GameWorld or Keybinds
+6. **Keybinds are invisible components** - They never render, just register
+   handlers
+7. **MapView and FirstPersonView are display-only** - Movement logic goes in
+   GameWorld or Keybinds
 8. **Legend system drives collision** - Use `isSolid()` for movement validation
 9. **No CSS or className** - ASCIITORIUM uses ASCII rendering, not DOM styling
-10. **Omit width/height props for auto-sizing** - Components have smart defaults (Text/Art/Column size to content, Button calculates from label, Row fills width)
+10. **Omit width/height props for auto-sizing** - Components have smart defaults
+    (Text/Art/Column size to content, Button calculates from label, Row fills
+    width)
+
 
----
 
 _End of Reference_