aidos-ui 4.0.0 → 4.0.1

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

package/src/pages/Dialog.mdx

@@ -1,15 +1,47 @@
 import { DialogTrigger } from "../examples/ExampleDialog.tsx";
+import { Button } from "../Button";
 
 # Dialog
 
-The `Dialog` component can be used to show a modal window on top of the main UI. When visible, it will trap focus and clicks to the underlying UI, which is the required behaviour for acceessibility.
+A modal dialog component that overlays the main UI. Dialogs trap focus and prevent interaction with the underlying content, following accessibility best practices.
+
+---
+
+## Props
+
+### Dialog component
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Dialog title displayed in the header |
+| `children` | `ReactNode` | Yes | Dialog content |
+| `close` | `() => void` | Yes | Function to close the dialog |
+
+### useDialog hook
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `DialogComponent` | `(props: { close: () => void } & Input) => JSX.Element` | Component to render inside the dialog |
+| `options.closeOnOutsideClick` | `boolean` | Whether clicking outside closes the dialog |
+
+Returns:
+- `open(input?: Input)` - Function to open the dialog with optional input data
+- `close()` - Function to close the dialog programmatically
+
+---
+
+## Basic usage
+
+Click the button to open a dialog:
 
 <DialogTrigger />
 
 ```js
-function ExampleDialog({ close }) {
+import { Dialog, useDialog } from "aidos-ui";
+
+function MyDialog({ close }) {
   return (
-    <Dialog close={close} label="Example">
+    <Dialog close={close} label="Settings">
       <Row padding="medium" align="center" justify="space-between">
         <Span>Dark mode</Span>
         <DarkModeToggle />
@@ -18,15 +50,148 @@ function ExampleDialog({ close }) {
   );
 }
 
-export function DialogTrigger() {
-  const { open } = useDialog<void>(
-    ({ close }) => <ExampleDialog close={close} />,
+function App() {
+  const { open } = useDialog(
+    ({ close }) => <MyDialog close={close} />,
     { closeOnOutsideClick: true }
   );
 
-  return <Button label="Show dialog" color={"positive"} onClick={() => open()} />;
+  return (
+    <Button color="positive" onClick={() => open()}>
+      Open Settings
+    </Button>
+  );
+}
+```
+
+---
+
+## Passing data to dialog
+
+Use TypeScript generics to pass data when opening the dialog:
+
+```js
+interface UserData {
+  name: string;
+  email: string;
 }
 
+function EditUserDialog({ close, name, email }: { close: () => void } & UserData) {
+  return (
+    <Dialog close={close} label="Edit User">
+      <Column padding="medium" gap="medium">
+        <TextInput value={name} onValueChange={() => {}} />
+        <TextInput value={email} onValueChange={() => {}} />
+        <Button color="positive" onClick={close}>
+          Save
+        </Button>
+      </Column>
+    </Dialog>
+  );
+}
+
+function App() {
+  const { open } = useDialog<UserData>(
+    ({ close, name, email }) => (
+      <EditUserDialog close={close} name={name} email={email} />
+    ),
+    { closeOnOutsideClick: false }
+  );
+
+  return (
+    <Button
+      color="primary"
+      onClick={() => open({ name: "John", email: "john@example.com" })}
+    >
+      Edit User
+    </Button>
+  );
+}
 ```
 
 ---
+
+## Dialog options
+
+### Close on outside click
+
+Control whether clicking the backdrop closes the dialog:
+
+```js
+// Dialog closes when clicking outside
+const { open } = useDialog(
+  ({ close }) => <MyDialog close={close} />,
+  { closeOnOutsideClick: true }
+);
+
+// Dialog stays open until explicitly closed
+const { open } = useDialog(
+  ({ close }) => <MyDialog close={close} />,
+  { closeOnOutsideClick: false }
+);
+```
+
+---
+
+## Closing the dialog
+
+Dialogs can be closed in several ways:
+
+1. **Close button** - Built into the Dialog header
+2. **Escape key** - Native dialog behavior
+3. **Outside click** - When `closeOnOutsideClick: true`
+4. **Programmatically** - Using the `close` function
+
+```js
+function ConfirmDialog({ close, onConfirm }) {
+  return (
+    <Dialog close={close} label="Confirm">
+      <Column padding="medium" gap="medium">
+        <P>Are you sure you want to proceed?</P>
+        <Row gap="medium" justify="end">
+          <Button bare color="primary" onClick={close}>
+            Cancel
+          </Button>
+          <Button
+            color="positive"
+            onClick={() => {
+              onConfirm();
+              close();
+            }}
+          >
+            Confirm
+          </Button>
+        </Row>
+      </Column>
+    </Dialog>
+  );
+}
+```
+
+---
+
+## Setup
+
+The `DialogProvider` must wrap your app to enable dialogs. This is typically included in the `Providers` component:
+
+```js
+import { Providers } from "aidos-ui";
+
+function App() {
+  return (
+    <Providers>
+      {/* Your app content */}
+    </Providers>
+  );
+}
+```
+
+---
+
+## Accessibility
+
+- Uses native `<dialog>` element with `showModal()` for proper modal behavior
+- Focus is trapped within the dialog
+- Escape key closes the dialog
+- Focus returns to the triggering element when closed
+- Backdrop prevents interaction with underlying content