@mythopoeia/ui

A comprehensive React component library for Mythopoeia applications. Provides consistent UI patterns, form inputs, layout components, modals, and control panels with a dark fantasy theme.

Installation

# From GitHub (recommended for external apps)
npm install https://gitpkg.now.sh/Placeholder-Game-Studio/mythopoeia/packages/ui?main

# Or from a specific version tag
npm install https://gitpkg.now.sh/Placeholder-Game-Studio/mythopoeia/packages/ui?v2.2.0

# Within the monorepo
npm install @mythopoeia/ui --workspace=your-app

Why gitpkg? npm can't install subdirectories from GitHub repos directly. gitpkg.now.sh is a free service that extracts subdirectories and serves them as installable packages.

Quick Start

import { Button, Modal, TextInput, ControlSection } from '@mythopoeia/ui';

// Import styles (required)
import '@mythopoeia/ui/styles';

function App() {
  return (
    <Button variant="primary" onClick={() => console.log('clicked')}>
      Click me
    </Button>
  );
}

Components

Layout Components

AppLayout

Three-section layout wrapper with responsive sidebar.

<AppLayout
  header={<AppHeader title="My App" />}
  sidebar={<ControlPanel>...</ControlPanel>}
  main={<MapCanvas />}
/>

AppHeader

Top navigation bar with title, subtitle, and action buttons.

<AppHeader
  title="World Generator"
  subtitle="Create fantasy worlds"
  actions={<Button>Save</Button>}
/>

Panel

Floating panel for displaying information.

<Panel
  title="Cell Info"
  position="center-left"
  size="md"
  collapsible
  showClose
  onClose={() => {}}
>
  <PanelSection title="Location">
    <PanelRow label="Position" value="(0.5, 0.3)" />
  </PanelSection>
</Panel>

Sidebar

Fixed sidebar with optional overlay mode for mobile.

<Sidebar
  position="right"
  width={320}
  title="Controls"
  collapsible
>
  {children}
</Sidebar>

Card

Content card container.

<Card title="Statistics" hoverable onClick={() => {}}>
  <p>Card content here</p>
</Card>

Modal Components

Modal

Base modal with overlay, escape key support, and click-outside-to-close.

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirm Action"
  size="md"
>
  <p>Are you sure?</p>
  <ModalFooter>
    <Button variant="secondary" onClick={onCancel}>Cancel</Button>
    <Button variant="primary" onClick={onConfirm}>Confirm</Button>
  </ModalFooter>
</Modal>

Button Components

Button

Multi-variant button with loading state.

<Button variant="primary" size="md" loading={isLoading}>
  Save World
</Button>

<Button variant="success" leftIcon={<CheckIcon />}>
  Complete
</Button>

Variants: primary, secondary, success, danger, ghost Sizes: sm, md, lg

IconButton

Icon-only button.

<IconButton
  icon={<CloseIcon />}
  aria-label="Close"
  variant="ghost"
/>

ButtonGroup

Group buttons together.

<ButtonGroup direction="horizontal" gap="md">
  <Button>One</Button>
  <Button>Two</Button>
</ButtonGroup>

Form Components

FormField

Wrapper for form inputs with label, tooltip, and error state.

<FormField
  label="Username"
  htmlFor="username"
  required
  tooltip="Your unique identifier"
  error={errors.username}
>
  <TextInput id="username" value={username} onChange={setUsername} />
</FormField>

TextInput

Text input with icon support.

<TextInput
  type="email"
  value={email}
  onChange={setEmail}
  placeholder="Enter email"
  size="md"
  error={!!emailError}
  leftIcon={<EmailIcon />}
/>

NumberInput

Numeric input with optional stepper buttons.

<NumberInput
  value={count}
  onChange={setCount}
  min={0}
  max={100}
  step={5}
  showStepper
/>

Slider

Range slider with value display.

<Slider
  value={plateCount}
  onChange={setPlateCount}
  min={10}
  max={500}
  step={10}
  showValue
  showMinMax
  formatValue={(v) => `${v} plates`}
/>

Select

Dropdown select with option groups.

<Select
  value={biome}
  onChange={setBiome}
  options={[
    { value: 'forest', label: 'Forest' },
    { value: 'desert', label: 'Desert' },
  ]}
  placeholder="Select biome"
/>

Toggle

On/off toggle switch.

<Toggle
  checked={enabled}
  onChange={setEnabled}
  label="Enable feature"
  labelPosition="right"
/>

Checkbox

Checkbox with indeterminate state support.

<Checkbox
  checked={accepted}
  onChange={setAccepted}
  label="I accept the terms"
  indeterminate={someChecked && !allChecked}
/>

Control Panel Components

Note: Control panel components are atomic - compose them with CollapsibleSection, StatusIndicator, and Button to build custom control panels with maximum flexibility.

Composition Example: Pipeline Control Section

import {
  CollapsibleSection,
  StatusIndicator,
  ControlGroup,
  Slider,
  Button
} from '@mythopoeia/ui';

<CollapsibleSection
  title="2. Plate Tectonics"
  statusIndicator={<StatusIndicator status="complete" />}
  defaultOpen={!collapsed}
>
  <ControlGroup
    label="Plate Count"
    displayValue={plateCount}
    tooltip="Number of tectonic plates (10-500)"
  >
    <Slider
      value={plateCount}
      onChange={setPlateCount}
      min={10}
      max={500}
      step={5}
      disabled={isGenerating}
    />
  </ControlGroup>

  <ControlGroup
    label="Continental Ratio"
    displayValue={`${(ratio * 100).toFixed(0)}%`}
    tooltip="Fraction of continental vs oceanic crust"
  >
    <Slider
      value={ratio}
      onChange={setRatio}
      min={0.2}
      max={0.5}
      step={0.05}
      disabled={isGenerating}
    />
  </ControlGroup>

  <Button
    variant="primary"
    onClick={handleGenerate}
    loading={isGenerating}
    disabled={!mesh}
    fullWidth
  >
    {isGenerating ? 'Generating...' : 'Generate Tectonics'}
  </Button>
</CollapsibleSection>

ControlGroup

Form field wrapper with label, value display, and optional tooltip.

<ControlGroup
  label="Temperature"
  displayValue={`${temp}°C`}
  tooltip="Average surface temperature"
  layout="vertical" // or 'horizontal'
>
  <Slider value={temp} onChange={setTemp} min={-50} max={50} />
</ControlGroup>

ControlRow

Horizontal layout for multiple control groups.

<ControlRow>
  <ControlGroup label="Width" displayValue={width}>
    <NumberInput value={width} onChange={setWidth} />
  </ControlGroup>
  <ControlGroup label="Height" displayValue={height}>
    <NumberInput value={height} onChange={setHeight} />
  </ControlGroup>
</ControlRow>

ControlPanel

Container for control sections.

<ControlPanel title="Physical World Generator">
  <CollapsibleSection title="Mesh" statusIndicator={<StatusIndicator status="complete" />}>
    {/* controls */}
  </CollapsibleSection>
  <CollapsibleSection title="Tectonics" statusIndicator={<StatusIndicator status="pending" />}>
    {/* controls */}
  </CollapsibleSection>
</ControlPanel>

Feedback Components

LoadingOverlay

Loading indicator with progress bar.

<LoadingOverlay
  message="Generating tectonics..."
  progress={45}
  position="bottom"
/>

ProgressBar

Animated progress indicator.

<ProgressBar progress={75} showPercentage />

StatusIndicator

Status badge.

<StatusIndicator status="complete" /> // 'pending' | 'generating' | 'complete'

CollapsibleSection

Generic collapsible section.

<CollapsibleSection
  title="Advanced Options"
  defaultOpen={false}
  statusIndicator={<StatusIndicator status="complete" />}
>
  {children}
</CollapsibleSection>

Styling

CSS Variables

The library uses CSS custom properties for theming. Import the base styles:

import '@mythopoeia/ui/styles';

Available CSS Variables

/* Colors */
--color-bg-primary: #1a1a1a;
--color-bg-secondary: #2a2a2a;
--color-accent-primary: #4a9eff;
--color-accent-success: #4ade80;
--color-text-primary: #e0e0e0;

/* Spacing */
--spacing-sm: 0.5rem;
--spacing-md: 0.75rem;
--spacing-lg: 1rem;

/* Typography */
--font-family-heading: 'Tagesschrift', serif;
--font-family-body: 'Nixie One', sans-serif;

/* See src/styles/theme.css for full list */

Custom Theming

Override CSS variables in your app:

:root {
  --color-accent-primary: #your-color;
  --color-bg-primary: #your-background;
}

TypeScript

All components are fully typed. Import types alongside components:

import { Button, ButtonProps, ButtonVariant } from '@mythopoeia/ui';

const variant: ButtonVariant = 'primary';

Peer Dependencies

{
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

Development

# Build
npm run build

# Watch mode
npm run dev

# Type check
npx tsc --noEmit

License

MIT