aidos-ui 4.0.0 → 4.0.1

package/src/jss.tsx

@@ -210,7 +210,7 @@ export function JSSProvider({
   children,
 }: {
   themes: { dark: Theme; light: Theme };
-  children: JSX.Element;
+  children: React.JSX.Element;
 }) {
   const stylesRef = useRef<string[] | null>(null);
 
@@ -534,10 +534,10 @@ const backgroundStyles = {
     backgroundColor: cssVar("--highlight"),
   },
   light: {
-    backgroundColor: "white",
+    backgroundColor: cssVar("--light-text"),
   },
   dark: {
-    backgroundColor: "black",
+    backgroundColor: cssVar("--primary-text"),
   },
   warning: {
     backgroundColor: cssVar("--warning"),

package/src/pages/Badge.mdx

@@ -1,30 +1,152 @@
 import { Badge } from "../Badge";
 import { Row } from "../Row";
+import { Column } from "../Column";
+import { Span } from "../Text";
+import { IconButton } from "../IconButton";
 
 # Badge
 
-This is a simple component that can be used to bring attention to a specific part of the user interface, for example an unread notification, an update, an important element...
+A small circular indicator used to draw attention to specific UI elements. Common uses include notification counts, status indicators, and visual markers.
 
 ---
 
-The `Badge` component supports all colours and sizes
+## Props
 
-<Row gap="large" align="center" justify="center">
-  <Badge size="xsmall" color="negative" />
-  <Badge size="small" color="warning" />
-  <Badge size="medium" color="highlight" />
-  <Badge size="large" color="secondary-background" />
-  <Badge size="xlarge" color="divider" />
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `Size` | `"medium"` | Badge size: `"xsmall"` (4px), `"small"` (6px), `"medium"` (12px), `"large"` (18px), `"xlarge"` (24px) |
+| `color` | `Color` | `"highlight"` | Background color from theme |
+
+---
+
+## Sizes
+
+<Row gap="large" align="center" justify="center" padding="medium">
+  <Column align="center" gap="small">
+    <Badge size="xsmall" />
+    <Span size="small" color="secondary">xsmall</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge size="small" />
+    <Span size="small" color="secondary">small</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge size="medium" />
+    <Span size="small" color="secondary">medium</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge size="large" />
+    <Span size="small" color="secondary">large</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge size="xlarge" />
+    <Span size="small" color="secondary">xlarge</Span>
+  </Column>
 </Row>
 
 ```js
-<Row gap="large" align="center" justify="center">
-  <Badge size="xsmall" color="negative" />
-  <Badge size="small" color="warning" />
-  <Badge size="medium" color="highlight" />
-  <Badge size="large" color="secondary-background" />
-  <Badge size="xlarge" color="divider" />
+<Badge size="xsmall" />  // 4px
+<Badge size="small" />   // 6px
+<Badge size="medium" />  // 12px (default)
+<Badge size="large" />   // 18px
+<Badge size="xlarge" />  // 24px
+```
+
+---
+
+## Colors
+
+<Row gap="large" align="center" justify="center" padding="medium">
+  <Column align="center" gap="small">
+    <Badge color="highlight" />
+    <Span size="small" color="secondary">highlight</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge color="negative" />
+    <Span size="small" color="secondary">negative</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge color="warning" />
+    <Span size="small" color="secondary">warning</Span>
+  </Column>
+  <Column align="center" gap="small">
+    <Badge color="divider" />
+    <Span size="small" color="secondary">divider</Span>
+  </Column>
 </Row>
+
+```js
+<Badge color="highlight" />  // Accent/brand color
+<Badge color="negative" />   // Error/alert
+<Badge color="warning" />    // Warning
+<Badge color="divider" />    // Neutral/muted
 ```
 
 ---
+
+## Common use cases
+
+### Notification indicator
+
+<Row gap="medium" align="center" padding="medium">
+  <Row jss={{ position: "relative" }}>
+    <IconButton bare icon="fa-bell" size="large" color="secondary" onClick={() => {}} />
+    <Badge size="small" color="negative" jss={{ position: "absolute", top: 0, right: 0 }} />
+  </Row>
+  <Span color="secondary">Unread notifications</Span>
+</Row>
+
+```js
+<Row jss={{ position: "relative" }}>
+  <IconButton bare icon="fa-bell" size="large" color="secondary" onClick={() => {}} />
+  <Badge
+    size="small"
+    color="negative"
+    jss={{ position: "absolute", top: 0, right: 0 }}
+  />
+</Row>
+```
+
+### Status indicator
+
+<Column gap="small" padding="medium">
+  <Row gap="small" align="center">
+    <Badge size="small" color="highlight" />
+    <Span>Online</Span>
+  </Row>
+  <Row gap="small" align="center">
+    <Badge size="small" color="warning" />
+    <Span>Away</Span>
+  </Row>
+  <Row gap="small" align="center">
+    <Badge size="small" color="divider" />
+    <Span>Offline</Span>
+  </Row>
+</Column>
+
+```js
+<Row gap="small" align="center">
+  <Badge size="small" color="highlight" />
+  <Span>Online</Span>
+</Row>
+```
+
+---
+
+## Visual markers
+
+Use badges to highlight new or important items:
+
+<Row gap="medium" align="center" padding="medium">
+  <Row gap="small" align="center">
+    <Span>New feature</Span>
+    <Badge size="xsmall" color="highlight" />
+  </Row>
+</Row>
+
+```js
+<Row gap="small" align="center">
+  <Span>New feature</Span>
+  <Badge size="xsmall" color="highlight" />
+</Row>
+```

package/src/pages/Button.mdx

@@ -1,105 +1,163 @@
 import { Button } from "../Button";
 import { Row } from "../Row";
+import { Column } from "../Column";
+import { Icon } from "../Icon";
 
 # Button
 
-The `Button` component can be used for the user to take actions with a single click, it supports a variety of styles each of them with different semantics.
+The `Button` component enables users to trigger actions with a single click. It supports multiple color variants for different semantic purposes and can include icons.
 
 ---
 
-## Button variants
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `string` | Yes | - | Button text label |
+| `color` | `InteractableColor` | Yes | - | `"positive"`, `"primary"`, `"negative"`, `"dark"`, `"light"` |
+| `onClick` | `function` | Yes | - | Click handler |
+| `bare` | `boolean` | No | `false` | Removes background for a lighter appearance |
+| `border` | `boolean` | No | `false` | Adds a border matching the text color |
+| `disabled` | `boolean` | No | `false` | Disables interaction |
+| `icon` | `IconType` | No | - | Icon to display alongside text |
+| `iconPosition` | `"left"` \| `"right"` | No | `"left"` | Icon placement relative to text |
+| `iconSize` | `Size` | No | `"medium"` | Icon size |
+| `size` | `Size` | No | `"medium"` | Text size |
+| `padding` | `Padding` | No | `"medium"` | Internal padding |
+| `bold` | `boolean` | No | `false` | Bold text |
 
-The basic `Button` comes in three main variants, each of them with a specific intent in mind. It also support a "disabled" variant, for cases where the button is not actionable.
+---
+
+## Color variants
+
+Each color variant communicates a different intent to users:
 
-- Positive: actions that are going to create something or strongly agree
-- Primary: actions that are less central to the user experience
-- Negative: actions that are going to delete data or remove something
-- Dark: primary actions in a dark theme
-- Light: primary actions in a light theme
-- Disabled: actions that are not available
+- **Positive**: Confirmations, submissions, primary actions
+- **Primary**: Secondary or neutral actions
+- **Negative**: Destructive actions like delete or remove
+- **Dark/Light**: Theme-specific variants for special contexts
 
 <Row gap="large" align="center" padding="large" justify="center">
-  <Button label="Positive" color="positive" onClick={() => {}} />
-  <Button label="Primary" color="primary" onClick={() => {}} />
-  <Button label="Negative" color="negative" onClick={() => {}} />
-  <Button label="Disabled" color="positive" disabled onClick={() => {}} />
-  <Button label="Dark" color="dark" onClick={() => {}} />
-  <Button label="Light" color="light" onClick={() => {}} />
+  <Button color="positive" onClick={() => {}}>Positive</Button>
+  <Button color="primary" onClick={() => {}}>Primary</Button>
+  <Button color="negative" onClick={() => {}}>Negative</Button>
+  <Button color="dark" onClick={() => {}}>Dark</Button>
+  <Button color="light" onClick={() => {}}>Light</Button>
 </Row>
 
 ```js
+<Button color="positive" onClick={() => {}}>Positive</Button>
+<Button color="primary" onClick={() => {}}>Primary</Button>
+<Button color="negative" onClick={() => {}}>Negative</Button>
+<Button color="dark" onClick={() => {}}>Dark</Button>
+<Button color="light" onClick={() => {}}>Light</Button>
+```
+
+---
+
+## Bare variant
+
+The `bare` prop removes the background color, creating a lighter appearance that integrates well within complex layouts or when you need a less prominent action.
+
 <Row gap="large" align="center" padding="large" justify="center">
-  <Button label="Positive" color="positive" onClick={() => {}} />
-  <Button label="Primary" color="primary" onClick={() => {}} />
-  <Button label="Negative" color="negative" onClick={() => {}} />
-  <Button label="Disabled" color="positive" disabled onClick={() => {}} />
-  <Button label="Dark" color="dark" onClick={() => {}} />
-  <Button label="Light" color="light" onClick={() => {}} />
+  <Button bare color="positive" onClick={() => {}}>Positive</Button>
+  <Button bare color="primary" onClick={() => {}}>Primary</Button>
+  <Button bare color="negative" onClick={() => {}}>Negative</Button>
+  <Button bare color="dark" onClick={() => {}}>Dark</Button>
+  <Button bare color="light" onClick={() => {}}>Light</Button>
 </Row>
+
+```js
+<Button bare color="positive" onClick={() => {}}>Positive</Button>
+<Button bare color="primary" onClick={() => {}}>Primary</Button>
+<Button bare color="negative" onClick={() => {}}>Negative</Button>
 ```
 
 ---
 
-## Bare button
+## With border
 
-The bare `Button` variants fulfill the same function than the basic counterparts but have a lighter style that can be more easily integrated in complex components.
+Add a `border` prop to give buttons a defined edge. Works well with `bare` for outlined button styles.
 
 <Row gap="large" align="center" padding="large" justify="center">
-  <Button bare label="Positive" color="positive" onClick={() => {}} />
-  <Button bare label="Primary" color="primary" onClick={() => {}} />
-  <Button bare label="Negative" color="negative" onClick={() => {}} />
-  <Button bare label="Disabled" color="positive" disabled onClick={() => {}} />
-  <Button bare label="Dark" color="dark" onClick={() => {}} />
-  <Button bare label="Light" color="light" onClick={() => {}} />
+  <Button border bare color="positive" onClick={() => {}}>Positive</Button>
+  <Button border bare color="primary" onClick={() => {}}>Primary</Button>
+  <Button border bare color="negative" onClick={() => {}}>Negative</Button>
 </Row>
 
 ```js
+<Button border bare color="positive" onClick={() => {}}>Outlined</Button>
+<Button border bare color="primary" onClick={() => {}}>Outlined</Button>
+<Button border bare color="negative" onClick={() => {}}>Outlined</Button>
+```
+
+---
+
+## With icon
+
+Buttons can include icons to reinforce their purpose. Use `icon` to specify the icon and `iconPosition` to place it on the left or right.
+
 <Row gap="large" align="center" padding="large" justify="center">
-  <Button bare label="Positive" color="positive" onClick={() => {}} />
-  <Button bare label="Primary" color="primary" onClick={() => {}} />
-  <Button bare label="Negative" color="negative" onClick={() => {}} />
-  <Button bare label="Disabled" color="positive" disabled onClick={() => {}} />
-  <Button bare label="Dark" color="dark" onClick={() => {}} />
-  <Button bare label="Light" color="light" onClick={() => {}} />
+  <Button color="positive" icon="fa-check" onClick={() => {}}>Confirm</Button>
+  <Button color="negative" icon="fa-trash" onClick={() => {}}>Delete</Button>
+  <Button color="primary" icon="fa-arrow-right" iconPosition="right" onClick={() => {}}>Next</Button>
 </Row>
+
+```js
+<Button color="positive" icon="fa-check" onClick={() => {}}>
+  Confirm
+</Button>
+
+<Button color="negative" icon="fa-trash" onClick={() => {}}>
+  Delete
+</Button>
+
+<Button color="primary" icon="fa-arrow-right" iconPosition="right" onClick={() => {}}>
+  Next
+</Button>
 ```
 
-## Border
+---
+
+## Disabled state
 
-The `Button` can have a border which will match the current text color
+Disabled buttons prevent interaction and display a muted appearance. The component uses `aria-disabled` for accessibility.
 
 <Row gap="large" align="center" padding="large" justify="center">
-  <Button border bare label="Positive" color="positive" onClick={() => {}} />
-  <Button border bare label="Primary" color="primary" onClick={() => {}} />
-  <Button border bare label="Negative" color="negative" onClick={() => {}} />
-  <Button
-    border
-    bare
-    label="Disabled"
-    color="positive"
-    disabled
-    onClick={() => {}}
-  />
-  <Button border bare label="Dark" color="dark" onClick={() => {}} />
-  <Button border bare label="Light" color="light" onClick={() => {}} />
+  <Button color="positive" disabled onClick={() => {}}>Disabled</Button>
+  <Button bare color="positive" disabled onClick={() => {}}>Disabled bare</Button>
+  <Button border bare color="positive" disabled onClick={() => {}}>Disabled outlined</Button>
 </Row>
 
 ```js
+<Button color="positive" disabled onClick={() => {}}>
+  Disabled
+</Button>
+```
+
+---
+
+## Sizes
+
+Control text size with the `size` prop. Available sizes: `"xsmall"`, `"small"`, `"medium"`, `"large"`, `"xlarge"`.
+
 <Row gap="large" align="center" padding="large" justify="center">
-  <Button border bare label="Positive" color="positive" onClick={() => {}} />
-  <Button border bare label="Primary" color="primary" onClick={() => {}} />
-  <Button border bare label="Negative" color="negative" onClick={() => {}} />
-  <Button
-    border
-    bare
-    label="Disabled"
-    color="positive"
-    disabled
-    onClick={() => {}}
-  />
-  <Button border bare label="Dark" color="dark" onClick={() => {}} />
-  <Button border bare label="Light" color="light" onClick={() => {}} />
+  <Button color="positive" size="small" onClick={() => {}}>Small</Button>
+  <Button color="positive" size="medium" onClick={() => {}}>Medium</Button>
+  <Button color="positive" size="large" onClick={() => {}}>Large</Button>
 </Row>
+
+```js
+<Button color="positive" size="small" onClick={() => {}}>Small</Button>
+<Button color="positive" size="medium" onClick={() => {}}>Medium</Button>
+<Button color="positive" size="large" onClick={() => {}}>Large</Button>
 ```
 
 ---
+
+## Accessibility
+
+- Buttons use semantic `<button>` elements
+- Disabled state is communicated via `aria-disabled` attribute
+- Focus states are clearly visible with outline styling
+- Click handlers are ignored when disabled, preventing accidental actions

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.