aidos-ui 4.0.0 → 4.0.2

package/src/pages/Calendar.mdx

@@ -1,11 +1,97 @@
 import { Calendar } from "../Calendar";
 import { Box } from "../Box";
+import { Row } from "../Row";
+import { Column } from "../Column";
 import { Badge } from "../Badge";
 import { Span, H3 } from "../Text";
+import { cssVar } from "../jss";
 
 # Calendar
 
-The calendar component is can be used to represent months, and is customisable through render callbacks for the header and cell elemtns
+A flexible calendar grid component for displaying months. Fully customizable through render callbacks for both header cells (weekday names) and day cells.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `Date` | Required | The month to display (uses year and month from this date) |
+| `header` | `(props) => JSX.Element` | Required | Render function for weekday header cells |
+| `cell` | `(props) => JSX.Element` | Required | Render function for day cells |
+| `jss` | `JSS` | - | Custom styles for the calendar grid |
+
+### Header render props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `weekday` | `string` | Localized weekday abbreviation (Mon, Tue, etc.) |
+
+### Cell render props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `date` | `Date` | The date for this cell |
+| `today` | `boolean` | Whether this date is today |
+| `outOfMonth` | `boolean` | Whether this date is outside the current month |
+| `top` | `boolean` | Whether this cell is in the top row |
+| `bottom` | `boolean` | Whether this cell is in the bottom row |
+| `left` | `boolean` | Whether this cell is in the leftmost column |
+| `right` | `boolean` | Whether this cell is in the rightmost column |
+
+---
+
+## Basic usage
+
+<Calendar
+  date={new Date()}
+  header={({ weekday }) => (
+    <Box padding="small" jss={{ textAlign: "center" }}>
+      <Span bold color="secondary" size="small">{weekday}</Span>
+    </Box>
+  )}
+  cell={({ today, date, outOfMonth }) => (
+    <Box padding="small" relative={true} jss={{ opacity: outOfMonth ? 0.3 : 1, textAlign: "center" }}>
+      {today && (
+        <Badge
+          size="xlarge"
+          color="highlight"
+          jss={{
+            position: "absolute",
+            top: "50%",
+            left: "50%",
+            transform: "translate(-50%, -50%)",
+            zIndex: 0,
+          }}
+        />
+      )}
+      <Span jss={{ position: "relative", zIndex: 1 }} color={today ? "light" : "primary"}>
+        {date.getDate()}
+      </Span>
+    </Box>
+  )}
+/>
+
+```js
+<Calendar
+  date={new Date()}
+  header={({ weekday }) => (
+    <Box padding="small" jss={{ textAlign: "center" }}>
+      <Span bold color="secondary" size="small">{weekday}</Span>
+    </Box>
+  )}
+  cell={({ today, date, outOfMonth }) => (
+    <Box padding="small" jss={{ opacity: outOfMonth ? 0.3 : 1 }}>
+      {today && <Badge color="highlight" />}
+      <Span>{date.getDate()}</Span>
+    </Box>
+  )}
+/>
+```
+
+---
+
+## With today indicator
 
 <Calendar
   date={new Date()}
@@ -36,7 +122,7 @@ The calendar component is can be used to represent months, and is customisable t
   date={new Date()}
   header={({ weekday }) => (
     <Box>
-      <H2>{weekday}</H2>
+      <H3>{weekday}</H3>
     </Box>
   )}
   cell={({ today, date, outOfMonth }) => (
@@ -58,3 +144,111 @@ The calendar component is can be used to represent months, and is customisable t
 ```
 
 ---
+
+## Using position props
+
+The cell render props include position information for styling borders and corners:
+
+```js
+<Calendar
+  date={new Date()}
+  header={({ weekday }) => <Span>{weekday}</Span>}
+  cell={({ date, outOfMonth, top, bottom, left, right }) => (
+    <Box
+      jss={{
+        opacity: outOfMonth ? 0.3 : 1,
+        borderTop: top ? "1px solid var(--divider)" : "none",
+        borderBottom: bottom ? "1px solid var(--divider)" : "none",
+        borderLeft: left ? "1px solid var(--divider)" : "none",
+        borderRight: right ? "1px solid var(--divider)" : "none",
+        borderTopLeftRadius: top && left ? 8 : 0,
+        borderTopRightRadius: top && right ? 8 : 0,
+        borderBottomLeftRadius: bottom && left ? 8 : 0,
+        borderBottomRightRadius: bottom && right ? 8 : 0,
+      }}
+    >
+      <Span>{date.getDate()}</Span>
+    </Box>
+  )}
+/>
+```
+
+---
+
+## Interactive calendar
+
+Create a date picker by adding click handlers:
+
+```js
+function DatePicker() {
+  const [selected, setSelected] = useState(null);
+  const [month, setMonth] = useState(new Date());
+
+  return (
+    <Column gap="medium">
+      <Row justify="space-between" align="center">
+        <IconButton
+          icon="fa-chevron-left"
+          onClick={() => setMonth(new Date(month.getFullYear(), month.getMonth() - 1))}
+        />
+        <Span bold>
+          {month.toLocaleDateString("en-US", { month: "long", year: "numeric" })}
+        </Span>
+        <IconButton
+          icon="fa-chevron-right"
+          onClick={() => setMonth(new Date(month.getFullYear(), month.getMonth() + 1))}
+        />
+      </Row>
+      <Calendar
+        date={month}
+        header={({ weekday }) => <Span size="small">{weekday}</Span>}
+        cell={({ date, outOfMonth, today }) => {
+          const isSelected = selected?.toDateString() === date.toDateString();
+          return (
+            <BaseButton
+              bare
+              onClick={() => !outOfMonth && setSelected(date)}
+              jss={{
+                opacity: outOfMonth ? 0.3 : 1,
+                backgroundColor: isSelected ? "var(--highlight)" : "transparent",
+                borderRadius: "50%",
+              }}
+            >
+              <Span color={isSelected ? "light" : "primary"}>
+                {date.getDate()}
+              </Span>
+            </BaseButton>
+          );
+        }}
+      />
+    </Column>
+  );
+}
+```
+
+---
+
+## Grid layout
+
+The Calendar uses CSS Grid with 7 columns (Mon-Sun). The header row and day cells flow naturally into the grid:
+
+```js
+// Custom grid styling
+<Calendar
+  date={new Date()}
+  jss={{
+    gap: 4,
+    padding: 16,
+    backgroundColor: "var(--secondary-background)",
+    borderRadius: 12,
+  }}
+  header={...}
+  cell={...}
+/>
+```
+
+---
+
+## Localization
+
+Weekday names are automatically localized using `Intl.DateTimeFormat` with UK English locale (week starts Monday). The calendar always displays Monday through Sunday.

package/src/pages/Card.mdx

@@ -1,71 +1,147 @@
 import { Card } from "../Card";
 import { Button } from "../Button";
 import { TextInput } from "../TextInput";
-import { TextArea } from "../TextArea";
-import { H2, P } from "../Text";
+import { Column } from "../Column";
+import { Row } from "../Row";
+import { H2, H3, P, Span } from "../Text";
+import { Icon } from "../Icon";
 
 # Card
 
-Cards can be used to make give cohesion to some UI elements, grouping them visually in a distinct way.
+A container component that groups related content with a distinct visual treatment. Cards provide elevation, background, and rounded corners to create visual hierarchy.
+
+---
+
+## Props
+
+Card extends all FlexLayout props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `padding` | `Padding` | `"large"` | Internal padding |
+| `gap` | `Gap` | `"large"` | Space between children |
+| `direction` | `"row"` \| `"column"` | `"column"` | Flex direction |
+| `align` | `Align` | - | Cross-axis alignment |
+| `justify` | `Justify` | - | Main-axis alignment |
+| `grow` | `boolean` | - | Allow card to grow |
+
+---
+
+## Basic card
+
+<Card>
+  <H3>Card title</H3>
+  <P>Cards group related content together with visual distinction from the surrounding interface.</P>
+</Card>
+
+```js
+<Card>
+  <H3>Card title</H3>
+  <P>Card content goes here...</P>
+</Card>
+```
+
+---
+
+## Contact form example
 
 <Card>
-  <H2>Contact Us</H2>
-  <P>If you have any questions or inquiries, please feel free to contact us.</P>
+  <H3>Contact Us</H3>
+  <P>Send us a message and we'll get back to you soon.</P>
   <TextInput
-    name="email"
-    placeholder="Email"
-    value={null}
-    padding={"medium"}
+    placeholder="Your email"
+    value=""
     type="email"
     onValueChange={() => {}}
   />
-  <TextArea
-    jss={{
-      resize: "vertical",
-    }}
-    name="message"
-    placeholder="Type your query here..."
-    value={null}
-    type="text"
+  <TextInput
+    placeholder="Your message"
+    value=""
     onValueChange={() => {}}
   />
-  <Button
-    jss={{ animation: "all 1s ease-out" }}
-    onClick={() => {}}
-    type="submit"
-    label="Subscribe"
-    color="positive"
-  />
+  <Button color="positive" onClick={() => {}}>
+    Send Message
+  </Button>
 </Card>
 
 ```js
 <Card>
-  <H2>Contact Us</H2>
-  <P>If you have any questions or inquiries, please feel free to contact us.</P>
+  <H3>Contact Us</H3>
+  <P>Send us a message and we'll get back to you soon.</P>
   <TextInput
-    name="email"
-    placeholder="Email"
-    value={null}
-    padding={"medium"}
+    placeholder="Your email"
+    value={email}
     type="email"
-    onValueChange={() => {}}
+    onValueChange={setEmail}
   />
-  <TextArea
-    jss={{
-      resize: "vertical",
-    }}
-    name="message"
-    placeholder="Type your query here..."
-    value={null}
-    type="text"
-    onValueChange={() => {}}
-  />
-  <Button
-    jss={{ animation: "all 1s ease-out" }}
-    onClick={() => {}}
-    type="submit"
-    label="Subscribe"
-    color="positive"
+  <TextInput
+    placeholder="Your message"
+    value={message}
+    onValueChange={setMessage}
   />
+  <Button color="positive" onClick={handleSubmit}>
+    Send Message
+  </Button>
 </Card>
 ```
+
+---
+
+## Custom padding and gap
+
+<Row gap="medium">
+  <Card padding="small" gap="small">
+    <Span>Small padding</Span>
+    <Span color="secondary">Compact layout</Span>
+  </Card>
+  <Card padding="xlarge" gap="medium">
+    <Span>Large padding</Span>
+    <Span color="secondary">Spacious layout</Span>
+  </Card>
+</Row>
+
+```js
+<Card padding="small" gap="small">
+  <Span>Compact card</Span>
+</Card>
+
+<Card padding="xlarge" gap="large">
+  <Span>Spacious card</Span>
+</Card>
+```
+
+---
+
+## Horizontal card
+
+Use `direction="row"` for horizontal layouts:
+
+<Card direction="row" align="center" gap="medium">
+  <Icon icon="fa-user" color="highlight" size="xlarge" />
+  <Column gap="none">
+    <Span bold>John Doe</Span>
+    <Span color="secondary" size="small">Software Engineer</Span>
+  </Column>
+</Card>
+
+```js
+<Card direction="row" align="center" gap="medium">
+  <Icon icon="fa-user" color="highlight" size="xlarge" />
+  <Column gap="none">
+    <Span bold>John Doe</Span>
+    <Span color="secondary" size="small">Software Engineer</Span>
+  </Column>
+</Card>
+```
+
+---
+
+## Use cases
+
+Cards are useful for:
+
+- **Forms** - Group related inputs together
+- **Profiles** - Display user or item information
+- **Summaries** - Highlight key metrics or stats
+- **Actions** - Group related actions with context
+- **Content sections** - Separate distinct content areas

package/src/pages/Checkbox.mdx

@@ -2,55 +2,130 @@ import { Checkbox } from "../Checkbox";
 import { StaticCheckbox } from "../StaticCheckbox";
 import { Column } from "../Column";
 import { Row } from "../Row";
+import { Span } from "../Text";
 
 # Checkbox
 
-The `Checkbox` component is an input of type checkbox with the visual style of a checkbox.
+A styled checkbox input with custom visual appearance. Built on native HTML checkbox for full accessibility support.
 
-<Column>
-  <Row padding="medium" gap="medium" justify="center" align="center">
+---
+
+## Props
+
+### Checkbox
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `checked` | `boolean` | Yes | - | Whether the checkbox is checked |
+| `onClick` | `() => void` | Yes | - | Called when checkbox is toggled |
+| `size` | `Size` | Yes | - | `"small"` (16px), `"medium"` (20px), `"large"` (24px) |
+
+Also accepts standard HTML input attributes.
+
+### StaticCheckbox
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `checked` | `boolean` | Yes | - | Whether the checkbox appears checked |
+| `size` | `Size` | Yes | - | `"small"`, `"medium"`, `"large"` |
+
+---
+
+## Sizes
+
+<Row padding="medium" gap="xlarge" justify="center" align="center">
+  <Column gap="small" align="center">
     <Checkbox size="small" checked={true} onClick={() => {}} />
+    <Span size="small" color="secondary">small</Span>
+  </Column>
+  <Column gap="small" align="center">
     <Checkbox size="medium" checked={true} onClick={() => {}} />
+    <Span size="small" color="secondary">medium</Span>
+  </Column>
+  <Column gap="small" align="center">
     <Checkbox size="large" checked={true} onClick={() => {}} />
-  </Row>
-  <Row padding="medium" gap="medium" justify="center" align="center">
-    <Checkbox size="small" checked={false} onClick={() => {}} />
-    <Checkbox size="medium" checked={false} onClick={() => {}} />
-    <Checkbox size="large" checked={false} onClick={() => {}} />
-  </Row>
-</Column>
+    <Span size="small" color="secondary">large</Span>
+  </Column>
+</Row>
 
 ```js
-<Column>
-  <Row padding="medium" gap="medium" justify="center" align="center">
-    <Checkbox size="small" checked={true} onClick={() => {}} />
-    <Checkbox size="medium" checked={true} onClick={() => {}} />
-    <Checkbox size="large" checked={true} onClick={() => {}} />
-  </Row>
-  <Row padding="medium" gap="medium" justify="center" align="center">
-    <Checkbox size="small" checked={false} onClick={() => {}} />
+<Checkbox size="small" checked={checked} onClick={toggle} />
+<Checkbox size="medium" checked={checked} onClick={toggle} />
+<Checkbox size="large" checked={checked} onClick={toggle} />
+```
+
+---
+
+## States
+
+<Row padding="medium" gap="xlarge" justify="center" align="center">
+  <Column gap="small" align="center">
     <Checkbox size="medium" checked={false} onClick={() => {}} />
-    <Checkbox size="large" checked={false} onClick={() => {}} />
-  </Row>
-</Column>
+    <Span size="small" color="secondary">unchecked</Span>
+  </Column>
+  <Column gap="small" align="center">
+    <Checkbox size="medium" checked={true} onClick={() => {}} />
+    <Span size="small" color="secondary">checked</Span>
+  </Column>
+</Row>
+
+```js
+const [checked, setChecked] = useState(false);
+
+<Checkbox
+  size="medium"
+  checked={checked}
+  onClick={() => setChecked(!checked)}
+/>
 ```
 
 ---
 
-## Static checkbox
+## StaticCheckbox
 
-The variant `StaticCheckbox` can be used when one only needs the visual representation of a checkbox but the `<input type="checkbox" />` does not make sense.
+Use `StaticCheckbox` when you need just the visual appearance without the underlying `<input>` element. Useful when the checkbox is part of a larger interactive component.
 
-<Row padding="medium" gap="medium" justify="center" align="center">
+<Row padding="medium" gap="large" justify="center" align="center">
   <StaticCheckbox size="small" checked={true} />
   <StaticCheckbox size="medium" checked={true} />
   <StaticCheckbox size="large" checked={true} />
 </Row>
 
 ```js
-<Row padding="medium" gap="medium" justify="center" align="center">
-  <StaticCheckbox size="small" checked={true} />
-  <StaticCheckbox size="medium" checked={true} />
-  <StaticCheckbox size="large" checked={true} />
+// Visual only - no input element
+<StaticCheckbox size="medium" checked={isSelected} />
+
+// Used within a custom list item
+<ListButtonItem
+  headline="Option"
+  addOn={<StaticCheckbox size="medium" checked={selected} />}
+  onClick={toggleSelection}
+/>
+```
+
+---
+
+## With label
+
+Checkboxes are typically paired with labels for better UX:
+
+```js
+<Row gap="small" align="center">
+  <Checkbox
+    size="medium"
+    checked={agreed}
+    onClick={() => setAgreed(!agreed)}
+  />
+  <Span>I agree to the terms and conditions</Span>
 </Row>
 ```
+
+---
+
+## Accessibility
+
+- Uses native `<input type="checkbox">` for full keyboard and screen reader support
+- Visual checkbox is layered over the hidden input
+- Focus ring appears on keyboard navigation
+- Press animation provides tactile feedback
+- `aria-checked` attribute reflects current state