@app-studio/web 0.9.31 → 0.9.33

package/docs/components/Calendar.mdx

@@ -0,0 +1,274 @@
+# Calendar
+
+A flexible calendar component with day, week, and month views for displaying and managing events. Features intelligent navigation (day-by-day, week-by-week, month-by-month), interactive hover cards for events and days, custom event rendering, and comprehensive styling customization.
+
+### **Import**
+  ```tsx
+  import { Calendar } from '@app-studio/web';
+  ```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const DefaultCalendar = () => {
+  return <Calendar />;
+};
+```
+
+### **With Events**
+Display events in the calendar with customizable event objects. Hover over events to see detailed information in a popup card, and hover over day cells to see a summary of the day's events.
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+import { CalendarEvent } from '../Calendar/Calendar.props';
+
+export const CalendarWithEvents = () => {
+  const events: CalendarEvent[] = [
+    {
+      id: 1,
+      title: 'Team Meeting',
+      start: new Date(2025, 9, 15, 10, 0),
+      end: new Date(2025, 9, 15, 11, 0),
+      description: 'Weekly team sync-up',
+    },
+    {
+      id: 2,
+      title: 'Project Deadline',
+      start: new Date(2025, 9, 18, 17, 0),
+      description: 'Submit final deliverables',
+    },
+  ];
+
+  return <Calendar events={events} />;
+};
+```
+
+**Interactive Features:**
+- **Event Hover Cards**: Hover over any event to see full details including title, date, time, and description
+- **Smart Navigation**: Navigation buttons automatically adapt to the current view (Previous/Next Day, Week, or Month)
+- **Fixed Cell Dimensions**: All day cells maintain consistent width (minimum 180px) and height for uniform layout
+- **Scrollable Content**: Events within each day cell scroll independently while maintaining cell dimensions
+
+### **Day View**
+Show a single day with all events for that day.
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const DayViewCalendar = () => {
+  return <Calendar initialView="day" />;
+};
+```
+
+### **Week View**
+Display a full week with events across all days.
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const WeekViewCalendar = () => {
+  return <Calendar initialView="week" />;
+};
+```
+
+### **Month View**
+Show the entire month with events distributed across days.
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const MonthViewCalendar = () => {
+  return <Calendar initialView="month" />;
+};
+```
+
+### **Custom Event Rendering**
+Customize how events are displayed using the `renderEvent` prop.
+
+```tsx
+import React from 'react';
+import { Vertical, Horizontal } from 'app-studio';
+import { Calendar } from '../Calendar';
+import { CalendarEvent, CalendarRenderEventContext } from '../Calendar/Calendar.props';
+import { Text } from '../../Text/Text';
+
+export const CustomRenderCalendar = () => {
+  const events: CalendarEvent[] = [
+    {
+      id: 1,
+      title: 'High Priority Meeting',
+      start: new Date(2025, 9, 15, 10, 0),
+      metadata: { priority: 'high' },
+    },
+  ];
+
+  const renderEvent = (event: CalendarEvent, context: CalendarRenderEventContext) => {
+    const priority = event.metadata?.priority as string;
+    
+    return (
+      <Vertical
+        gap={8}
+        padding={12}
+        borderRadius={12}
+        backgroundColor="color.error.50"
+        borderWidth={1}
+        borderStyle="solid"
+        borderColor="color.error.200"
+      >
+        <Text fontWeight="600">{event.title}</Text>
+        <Text fontSize={12} color="color.error.600">{priority}</Text>
+      </Vertical>
+    );
+  };
+
+  return <Calendar events={events} renderEvent={renderEvent} />;
+};
+```
+
+### **Week Starts On**
+Configure which day the week starts on (0 = Sunday, 1 = Monday, etc.).
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const WeekStartsOnMonday = () => {
+  return <Calendar weekStartsOn={1} />;
+};
+```
+
+### **Custom Styles**
+Customize the appearance of calendar elements using the `views` prop.
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const CustomStyledCalendar = () => {
+  return (
+    <Calendar
+      views={{
+        container: {
+          backgroundColor: 'color.primary.50',
+          borderColor: 'color.primary.300',
+        },
+        headerTitle: {
+          color: 'color.primary.700',
+          fontSize: 24,
+        },
+        event: {
+          backgroundColor: 'color.primary.100',
+          borderColor: 'color.primary.400',
+        },
+      }}
+    />
+  );
+};
+```
+
+### **Fixed Height with Scrolling**
+Set a fixed height for the calendar with scrollable content areas.
+
+```tsx
+import React from 'react';
+import { Calendar } from '../Calendar';
+
+export const FixedHeightCalendar = () => {
+  const events = [
+    {
+      id: 1,
+      title: 'Team Meeting',
+      start: new Date(2025, 9, 15, 10, 0),
+      end: new Date(2025, 9, 15, 11, 0),
+    },
+    // ... more events
+  ];
+
+  return <Calendar events={events} height="600px" initialView="week" />;
+};
+```
+
+## Props
+
+| Prop           | Type                    | Description                                                    | Default     |
+| -------------- | ----------------------- | -------------------------------------------------------------- | ----------- |
+| events         | CalendarEvent[]         | Array of events to display in the calendar.                   | []          |
+| initialDate    | Date \| string          | Starting date displayed in the calendar.                       | new Date()  |
+| initialView    | 'day' \| 'week' \| 'month' | Initial visible view.                                       | 'month'     |
+| weekStartsOn   | 0-6                     | First day of the week (0 = Sunday, 1 = Monday, etc.).         | 0           |
+| height         | string \| number        | Height of the calendar container (enables scrolling).          | '800px'     |
+| renderEvent    | function                | Custom render method for events.                               | -           |
+| onDateChange   | function                | Callback when the visible anchor date changes.                 | -           |
+| onViewChange   | function                | Callback when the active view changes.                         | -           |
+| views          | CalendarViews           | Customize styling of calendar areas.                           | -           |
+
+## CalendarEvent Interface
+
+| Property    | Type                  | Description                                      |
+| ----------- | --------------------- | ------------------------------------------------ |
+| id          | string \| number      | Unique identifier for the event.                 |
+| title       | string                | Event title shown in the calendar cell.          |
+| start       | Date \| string        | Start date/time of the event.                    |
+| end         | Date \| string        | Optional end date/time of the event.             |
+| description | string                | Optional description or supporting information.  |
+| metadata    | Record<string, unknown> | Additional metadata for the event.             |
+
+## CalendarViews Interface
+
+Customize the appearance of different calendar elements. All elements support the `views` prop for complete customization:
+
+### Container & Layout
+- `container` - Main calendar container (ViewProps)
+- `header` - Header section (ViewProps)
+- `grid` - Calendar grid container (ViewProps)
+
+### Header Elements
+- `headerTitle` - Title text in header (TextProps)
+- `navigation` - Navigation buttons container (ViewProps)
+- `navigationButton` - Navigation button props (ButtonProps)
+- `viewSwitcher` - View switcher buttons container (ViewProps)
+- `viewButton` - View button props (ButtonProps)
+
+### Weekday Header
+- `weekdayRow` - Weekday row container (ViewProps)
+- `weekdayHeader` - Individual weekday header cell (ViewProps)
+- `weekdayLabel` - Weekday label text (TextProps)
+
+### Week & Day Structure
+- `weekRow` - Week row container (ViewProps)
+- `dayColumn` - Individual day column/cell (ViewProps)
+- `dayHeader` - Day header within cell (ViewProps)
+- `dayNumber` - Day number text (TextProps)
+- `dayMeta` - Day metadata text (TextProps)
+
+### Events
+- `events` - Events container within day (ViewProps)
+- `event` - Individual event container (ViewProps)
+- `eventTitle` - Event title text (TextProps)
+- `eventTime` - Event time text (TextProps)
+- `emptyState` - Empty state text when no events (TextProps)
+
+### Example: Complete Customization
+
+```tsx
+<Calendar
+  events={events}
+  views={{
+    container: { backgroundColor: 'color.gray.50', padding: 32 },
+    headerTitle: { fontSize: 24, color: 'color.primary.700' },
+    weekdayRow: { backgroundColor: 'color.primary.50', borderRadius: 8 },
+    weekdayLabel: { fontSize: 16, fontWeight: '700' },
+    dayColumn: { padding: 20, borderRadius: 16, borderWidth: 2 },
+    dayNumber: { fontSize: 20, color: 'color.primary.700' },
+    event: { padding: 16, backgroundColor: 'color.primary.100' },
+    eventTitle: { fontSize: 16, fontWeight: '700' },
+  }}
+/>
+```
+

package/docs/components/Card.mdx

@@ -0,0 +1,341 @@
+# Card
+
+A flexible container component for organizing and displaying content.
+
+### **Import**
+  ```tsx
+  import { Card } from '@app-studio/web';
+  ```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+
+export const DefaultDemo = () => {
+  return (
+    <Card>
+      <Text>This is a default card with simple content.</Text>
+    </Card>
+  );
+};
+```
+
+### **Variants**
+Different visual styles for the card.
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Vertical } from 'app-studio';
+
+export const VariantsDemo = () => {
+  return (
+    <Vertical gap={20}>
+      <Card variant="default">
+        <Text>Default Card</Text>
+        <Text color="color.gray.500">
+          This is a card with the default variant.
+        </Text>
+      </Card>
+
+      <Card variant="outlined">
+        <Text>Outlined Card</Text>
+        <Text color="color.gray.500">
+          This card has a border around it.
+        </Text>
+      </Card>
+
+      <Card variant="elevated">
+        <Text>Elevated Card</Text>
+        <Text color="color.gray.500">
+          This card has a shadow to give it an elevated appearance.
+        </Text>
+      </Card>
+    </Vertical>
+  );
+};
+```
+
+### **Structured Layout**
+Using Card.Header, Card.Content, and Card.Footer for structured layout.
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Horizontal } from 'app-studio';
+import { Button } from '../../Button/Button';
+
+export const StructuredDemo = () => {
+  return (
+    <Card>
+      <Card.Header>
+        <Text fontWeight="bold" fontSize={18}>Card Title</Text>
+      </Card.Header>
+
+      <Card.Content>
+        <Text>
+          This card uses the structured layout with separate header, content, and footer sections.
+          The content area is where the main information goes.
+        </Text>
+      </Card.Content>
+
+      <Card.Footer>
+        <Horizontal justifyContent="flex-end" gap={10}>
+          <Button variant="outline">Cancel</Button>
+          <Button>Submit</Button>
+        </Horizontal>
+      </Card.Footer>
+    </Card>
+  );
+};
+```
+
+### **Shapes**
+Different corner styles for the card.
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Vertical } from 'app-studio';
+import { Shape } from '../Card/Card.type';
+
+export const ShapesDemo = () => {
+  const shapes: Shape[] = ['sharp', 'rounded', 'pillShaped'];
+
+  return (
+    <Vertical gap={20}>
+      {shapes.map((shape) => (
+        <Card key={shape} shape={shape} variant="outlined">
+          <Text fontWeight="bold">{shape} Card</Text>
+          <Text color="color.gray.500">
+            This card has {shape === 'sharp' ? 'no' : shape} corners.
+          </Text>
+        </Card>
+      ))}
+    </Vertical>
+  );
+};
+```
+
+### **Sizes**
+Different padding sizes for the card.
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Vertical } from 'app-studio';
+import { Size } from '../Card/Card.type';
+
+export const SizesDemo = () => {
+  const sizes: Size[] = ['sm', 'md', 'lg'];
+
+  return (
+    <Vertical gap={20}>
+      {sizes.map((size) => (
+        <Card key={size} size={size} variant="outlined">
+          <Text fontWeight="bold">{size.toUpperCase()} Size</Text>
+          <Text color="color.gray.500">
+            This card has {size} padding.
+          </Text>
+        </Card>
+      ))}
+    </Vertical>
+  );
+};
+```
+
+### **Custom Styling**
+Customize the appearance of the card.
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Horizontal } from 'app-studio';
+import { Button } from '../../Button/Button';
+
+export const CustomDemo = () => {
+  return (
+    <Card
+      views={{
+        container: {
+          backgroundColor: 'color.blue.50',
+          borderRadius: '16px',
+          boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
+        },
+        header: {
+          backgroundColor: 'color.blue.500',
+          color: 'color.white',
+          padding: '16px',
+          borderBottomWidth: '0',
+        },
+        content: {
+          padding: '24px',
+        },
+        footer: {
+          padding: '16px',
+          backgroundColor: 'color.gray.50',
+          borderTopWidth: '0',
+        },
+      }}
+    >
+      <Card.Header>
+        <Text fontWeight="bold" fontSize={18} color="white">
+          Custom Styled Card
+        </Text>
+      </Card.Header>
+
+      <Card.Content>
+        <Text>
+          This card has custom styling applied to all its parts.
+          You can customize the container, header, content, and footer.
+        </Text>
+      </Card.Content>
+
+      <Card.Footer>
+        <Horizontal justifyContent="flex-end" gap={10}>
+          <Button variant="outline">Cancel</Button>
+          <Button>Submit</Button>
+        </Horizontal>
+      </Card.Footer>
+    </Card>
+  );
+};
+```
+
+### **Context-Based Styling**
+The Card component uses a context-based styling system that allows styles to be passed down from the parent Card to its child components (Header, Content, Footer).
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Button } from '../../Button/Button';
+import { Horizontal } from 'app-studio';
+
+export const ContextStylingDemo = () => {
+  return (
+    <Card
+      views={{
+        // These styles will be passed down to all child components via context
+        container: {
+          backgroundColor: 'color.blue.50',
+          borderRadius: '12px',
+          boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
+        },
+        header: {
+          backgroundColor: 'color.blue.100',
+          padding: '16px',
+          borderBottomColor: 'color.blue.200',
+        },
+        content: {
+          padding: '24px',
+        },
+        footer: {
+          backgroundColor: 'color.blue.100',
+          padding: '16px',
+          borderTopColor: 'color.blue.200',
+        },
+      }}
+    >
+      <Card.Header>
+        <Text fontWeight="bold" fontSize={18}>
+          Context-Based Styling
+        </Text>
+      </Card.Header>
+
+      <Card.Content>
+        <Text>
+          This card demonstrates the improved context-based styling system.
+          The styles defined in the Card's "views" prop are automatically
+          passed down to the Header, Content, and Footer components.
+        </Text>
+      </Card.Content>
+
+      <Card.Footer>
+        <Horizontal justifyContent="flex-end" gap={10}>
+          <Button variant="outline">Cancel</Button>
+          <Button>Submit</Button>
+        </Horizontal>
+      </Card.Footer>
+    </Card>
+  );
+};
+```
+
+### **Theme Mode Support**
+The Card component supports both light and dark themes through the `themeMode` prop.
+
+```tsx
+import React from 'react';
+import { Card } from '../Card';
+import { Text } from '../../Text/Text';
+import { Horizontal, Vertical } from 'app-studio';
+import { Button } from '../../Button/Button';
+
+export const DarkModeExample = () => {
+  return (
+    <Vertical gap={20}>
+      <Text fontSize={20} fontWeight="bold">Light Mode Cards</Text>
+      <Horizontal gap={20} alignItems="flex-start">
+        <Card variant="default" themeMode="light">
+          <Card.Header>
+            <Text fontWeight="bold">Default Card (Light)</Text>
+          </Card.Header>
+          <Card.Content>
+            <Text>This card uses light mode styling.</Text>
+          </Card.Content>
+          <Card.Footer>
+            <Button size="sm">Action</Button>
+          </Card.Footer>
+        </Card>
+
+        <Card variant="outlined" themeMode="light">
+          <Card.Header>
+            <Text fontWeight="bold">Outlined Card (Light)</Text>
+          </Card.Header>
+          <Card.Content>
+            <Text>This card uses light mode styling with an outline.</Text>
+          </Card.Content>
+          <Card.Footer>
+            <Button size="sm">Action</Button>
+          </Card.Footer>
+        </Card>
+      </Horizontal>
+
+      <Text fontSize={20} fontWeight="bold" marginTop={40}>Dark Mode Cards</Text>
+      <Horizontal gap={20} alignItems="flex-start">
+        <Card variant="default" themeMode="dark">
+          <Card.Header>
+            <Text fontWeight="bold">Default Card (Dark)</Text>
+          </Card.Header>
+          <Card.Content>
+            <Text>This card uses dark mode styling.</Text>
+          </Card.Content>
+          <Card.Footer>
+            <Button size="sm">Action</Button>
+          </Card.Footer>
+        </Card>
+
+        <Card variant="outlined" themeMode="dark">
+          <Card.Header>
+            <Text fontWeight="bold">Outlined Card (Dark)</Text>
+          </Card.Header>
+          <Card.Content>
+            <Text>This card uses dark mode styling with an outline.</Text>
+          </Card.Content>
+          <Card.Footer>
+            <Button size="sm">Action</Button>
+          </Card.Footer>
+        </Card>
+      </Horizontal>
+    </Vertical>
+  );
+};
+```