aidos-ui 4.0.0 → 4.0.1

package/src/pages/TextPairing.mdx

@@ -1,155 +1,204 @@
 import { TextPairing } from "../TextPairing";
 import { Column } from "../Column";
-import { ListDivider } from "../ListDivider";
+import { Row } from "../Row";
 import { Icon } from "../Icon";
 import { cssVar } from "../jss";
 
 # TextPairing
 
-The `TextPairing` is a seemingly simple component that can be used to represent multiple visual ideas. Many of the other components use it to create more complex elements.
+A versatile component for displaying a headline with optional body text and add-ons. TextPairing is the building block for list items, cards, and other compound components.
 
-In its simplest form a `TextPairing` is formed of two text elements (headline and body) laid out vertically. However it accepts multiple props to enable much more complex representations.
+---
 
-<Column
-  jss={{ [" > *"]: { borderBottom: `1px solid ${cssVar("--divider")}` } }}
->
-  <TextPairing headline="Headline" body="Body" />
-  <TextPairing headline="Headline" headlineBold body="Body" />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-  />
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `headline` | `ReactNode` | Yes | - | Primary text content |
+| `body` | `ReactNode` | No | - | Secondary text below headline |
+| `headlineColor` | `TextColor` | No | `"primary"` | Headline text color |
+| `headlineSize` | `Size` | No | `"medium"` | Headline text size |
+| `headlineBold` | `boolean` | No | `false` | Bold headline text |
+| `headlineAddOn` | `ReactNode` | No | - | Element displayed after headline |
+| `bodyColor` | `TextColor` | No | `"secondary"` | Body text color |
+| `bodySize` | `Size` | No | `"medium"` | Body text size |
+| `addOn` | `ReactNode` | No | - | Element displayed beside the text content |
+| `addOnPosition` | `"start"` \| `"end"` | No | `"start"` | Add-on placement |
+| `gap` | `Gap` | No | `"small"` | Space between add-on and text |
+| `padding` | `Padding` | No | - | Internal padding |
+| `align` | `Align` | No | `"stretch"` | Vertical alignment |
+| `grow` | `boolean` | No | `false` | Allow component to grow |
+| `shrink` | `boolean` | No | `false` | Allow component to shrink |
+
+---
+
+## Basic usage
+
+At its simplest, TextPairing displays a headline and body text vertically stacked.
+
+<Column gap="large">
+  <TextPairing headline="Headline" body="Body text goes here" />
+  <TextPairing headline="Bold headline" headlineBold body="With supporting body text" />
+</Column>
+
+```js
+<TextPairing headline="Headline" body="Body text" />
+
+<TextPairing
+  headline="Bold headline"
+  headlineBold
+  body="With supporting body text"
+/>
+```
+
+---
+
+## Customizing text styles
+
+Control the size and color of both headline and body independently.
+
+<Column gap="large">
   <TextPairing
-    headline="Headline"
-    headlineBold
+    headline="Large headline"
     headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-  />
-  <TextPairing
-    headline="Headline"
     headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
+    body="Smaller subtle body"
     bodySize="small"
-  />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
     bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
   />
   <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
-    gap="medium"
+    headline="Highlight headline"
+    headlineColor="highlight"
+    body="Secondary body text"
+    bodyColor="secondary"
   />
+</Column>
+
+```js
+<TextPairing
+  headline="Large headline"
+  headlineSize="large"
+  headlineBold
+  body="Smaller subtle body"
+  bodySize="small"
+  bodyColor="subtle"
+/>
+
+<TextPairing
+  headline="Highlight headline"
+  headlineColor="highlight"
+  body="Secondary body text"
+/>
+```
+
+---
+
+## With add-on
+
+Add icons, avatars, or other elements alongside the text content. Control placement with `addOnPosition`.
+
+<Column gap="large">
   <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
+    headline="Notification"
+    body="You have a new message"
+    addOn={<Icon icon="fa-bell" color="highlight" size="large" />}
     gap="medium"
-    addOnPosition="end"
   />
   <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
-    headlineAddOn={<Icon icon="fa-plus" color="primary" size="small" />}
-    gap="medium"
+    headline="Settings"
+    body="Configure your preferences"
+    addOn={<Icon icon="fa-cog" color="secondary" size="large" />}
     addOnPosition="end"
+    gap="medium"
   />
 </Column>
 
 ```js
-<Column
-  jss={{ [" > *"]: { borderBottom: `1px solid ${cssVar("--divider")}` } }}
->
-  <TextPairing headline="Headline" body="Body" />
-  <TextPairing headline="Headline" headlineBold body="Body" />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-  />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-  />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-  />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
-  />
-  <TextPairing
-    headline="Headline"
-    headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
-    gap="medium"
-  />
+// Add-on at start (default)
+<TextPairing
+  headline="Notification"
+  body="You have a new message"
+  addOn={<Icon icon="fa-bell" color="highlight" size="large" />}
+  gap="medium"
+/>
+
+// Add-on at end
+<TextPairing
+  headline="Settings"
+  body="Configure your preferences"
+  addOn={<Icon icon="fa-cog" color="secondary" size="large" />}
+  addOnPosition="end"
+  gap="medium"
+/>
+```
+
+---
+
+## With headline add-on
+
+Place small elements directly after the headline text, such as badges or status indicators.
+
+<Column gap="large">
   <TextPairing
-    headline="Headline"
+    headline="New feature"
     headlineBold
-    headlineSize="large"
-    body="Body"
-    bodyColor="subtle"
-    bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
-    gap="medium"
-    addOnPosition="end"
+    headlineAddOn={<Icon icon="fa-star" color="highlight" size="small" />}
+    body="Check out what's new"
   />
+</Column>
+
+```js
+<TextPairing
+  headline="New feature"
+  headlineBold
+  headlineAddOn={<Icon icon="fa-star" color="highlight" size="small" />}
+  body="Check out what's new"
+/>
+```
+
+---
+
+## Complete example
+
+Combining all options for a rich list item appearance.
+
+<Column gap="medium">
   <TextPairing
-    headline="Headline"
+    headline="John Doe"
     headlineBold
     headlineSize="large"
-    body="Body"
+    headlineAddOn={<Icon icon="fa-check-circle" color="highlight" size="small" />}
+    body="Senior Software Engineer"
     bodyColor="subtle"
     bodySize="small"
-    addOn={<Icon icon="fa-bicycle" color="primary" size="xxlarge" />}
-    headlineAddOn={<Icon icon="fa-plus" color="primary" size="small" />}
+    addOn={<Icon icon="fa-user" color="primary" size="xlarge" />}
     gap="medium"
-    addOnPosition="end"
+    padding="medium"
   />
 </Column>
+
+```js
+<TextPairing
+  headline="John Doe"
+  headlineBold
+  headlineSize="large"
+  headlineAddOn={<Icon icon="fa-check-circle" color="highlight" size="small" />}
+  body="Senior Software Engineer"
+  bodyColor="subtle"
+  bodySize="small"
+  addOn={<Icon icon="fa-user" color="primary" size="xlarge" />}
+  gap="medium"
+  padding="medium"
+/>
 ```
 
 ---
+
+## Use cases
+
+TextPairing is commonly used within:
+
+- **List items** - Display title and description with icons
+- **Cards** - Header sections with titles and subtitles
+- **Navigation** - Menu items with labels and descriptions
+- **Settings** - Option labels with explanatory text

package/src/pages/TimeInput.mdx

@@ -1,45 +1,49 @@
 import { Column } from "../Column";
+import { Row } from "../Row";
 import { TimeInput } from "../TimeInput";
 import { Icon } from "../Icon";
+import { Span } from "../Text";
 
 # TimeInput
 
-The `TimeInput` component can be used to get the time (hour and minute) from the user.
+A styled time picker component that wraps the native HTML `<input type="time">` element. Returns hours and minutes as a Date object.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `time` | `Date` | Required | Current time value |
+| `onTimeChange` | `(date: Date) => void` | Required | Called when time changes |
+| `bare` | `boolean` | `false` | Remove border and background styling |
+| `disabled` | `boolean` | - | Disables the input |
+| `addOn` | `ReactNode` | - | Icon or element to display |
+| `addOnPosition` | `"start" \| "end"` | `"start"` | Position of the add-on |
+| `gap` | `Gap` | `"none"` | Space between elements |
+| `padding` | `Padding` | `"small"` | Container padding |
+
+---
+
+## Basic usage
 
 <Column gap="medium" jss={{ maxWidth: 150 }}>
   <TimeInput time={new Date()} onTimeChange={() => {}} />
-  <TimeInput
-    addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
-    time={new Date()}
-    onTimeChange={() => {}}
-  />
-  <TimeInput
-    addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
-    addOnPosition="end"
-    time={new Date()}
-    onTimeChange={() => {}}
-  />
-  <TimeInput bare time={new Date()} onTimeChange={() => {}} />
-  <TimeInput
-    bare
-    addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
-    time={new Date()}
-    onTimeChange={() => {}}
-  />
-  <TimeInput
-    bare
-    addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
-    addOnPosition="end"
-    time={new Date()}
-    onTimeChange={() => {}}
-  />
-  <TimeInput disabled time={new Date()} onTimeChange={() => {}} />
-  <TimeInput bare disabled time={new Date()} onTimeChange={() => {}} />
 </Column>
 
 ```js
-<Column gap="medium" jss={{ maxWidth: 150 }}>
-  <TimeInput time={new Date()} onTimeChange={() => {}} />
+const [time, setTime] = useState(new Date());
+
+<TimeInput time={time} onTimeChange={setTime} />
+```
+
+---
+
+## With icon
+
+Add a clock icon for visual context:
+
+<Column gap="medium" jss={{ maxWidth: 200 }}>
   <TimeInput
     addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
     time={new Date()}
@@ -51,6 +55,32 @@ The `TimeInput` component can be used to get the time (hour and minute) from the
     time={new Date()}
     onTimeChange={() => {}}
   />
+</Column>
+
+```js
+// Icon at start (default)
+<TimeInput
+  addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
+  time={time}
+  onTimeChange={setTime}
+/>
+
+// Icon at end
+<TimeInput
+  addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
+  addOnPosition="end"
+  time={time}
+  onTimeChange={setTime}
+/>
+```
+
+---
+
+## Bare variant
+
+The bare variant removes the border and background, useful for inline editing:
+
+<Column gap="medium" jss={{ maxWidth: 200 }}>
   <TimeInput bare time={new Date()} onTimeChange={() => {}} />
   <TimeInput
     bare
@@ -58,16 +88,91 @@ The `TimeInput` component can be used to get the time (hour and minute) from the
     time={new Date()}
     onTimeChange={() => {}}
   />
-  <TimeInput
-    bare
-    addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
-    addOnPosition="end"
-    time={new Date()}
-    onTimeChange={() => {}}
-  />
+</Column>
+
+```js
+<TimeInput bare time={time} onTimeChange={setTime} />
+
+<TimeInput
+  bare
+  addOn={<Icon icon="fa-clock-o" color="primary" size="medium" />}
+  time={time}
+  onTimeChange={setTime}
+/>
+```
+
+---
+
+## Disabled state
+
+<Column gap="medium" jss={{ maxWidth: 200 }}>
   <TimeInput disabled time={new Date()} onTimeChange={() => {}} />
   <TimeInput bare disabled time={new Date()} onTimeChange={() => {}} />
 </Column>
+
+```js
+<TimeInput disabled time={time} onTimeChange={setTime} />
+<TimeInput bare disabled time={time} onTimeChange={setTime} />
+```
+
+---
+
+## Working with Date objects
+
+The component works with JavaScript Date objects. Only the hours and minutes are used:
+
+```js
+function ScheduleForm() {
+  const [startTime, setStartTime] = useState(new Date());
+  const [endTime, setEndTime] = useState(new Date());
+
+  // Get just the time portion
+  const formatTime = (date) => {
+    return date.toLocaleTimeString("en-US", {
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  };
+
+  return (
+    <Column gap="medium">
+      <Row gap="medium" align="center">
+        <Span>From:</Span>
+        <TimeInput time={startTime} onTimeChange={setStartTime} />
+      </Row>
+      <Row gap="medium" align="center">
+        <Span>To:</Span>
+        <TimeInput time={endTime} onTimeChange={setEndTime} />
+      </Row>
+      <Span color="secondary">
+        Selected: {formatTime(startTime)} - {formatTime(endTime)}
+      </Span>
+    </Column>
+  );
+}
 ```
 
 ---
+
+## Setting initial time
+
+```js
+// Current time
+const [time, setTime] = useState(new Date());
+
+// Specific time (e.g., 9:30 AM)
+const [time, setTime] = useState(() => {
+  const date = new Date();
+  date.setHours(9, 30, 0, 0);
+  return date;
+});
+```
+
+---
+
+## Accessibility
+
+- Uses native `<input type="time">` for full browser accessibility support
+- Focus states are visually indicated
+- Works with keyboard navigation
+- Screen readers announce the input purpose

package/src/pages/Tooltip.mdx

@@ -1,28 +1,115 @@
 import { Button } from "../Button";
+import { IconButton } from "../IconButton";
+import { Row } from "../Row";
 import { Tooltip } from "../Tooltip";
 
 # Tooltip
 
-The `Tooltip` component can be used to display light contextual information about an element. The content of a tooltip should not be interactable (to make it accessible interactable elements should be dialgs) so they only accept content of type `string`.
+Displays contextual information when hovering over an element. Tooltips are for informational text only and should not contain interactive content.
 
-<Tooltip content="Tooltip here">
-  <Button
-    bare
-    label="Hover to show tooltip"
-    color="positive"
-    onClick={() => {}}
-  />
+---
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `content` | `string` | Yes | - | Text to display in the tooltip |
+| `children` | `ReactNode` | Yes | - | Element that triggers the tooltip on hover |
+| `tag` | `keyof HTMLElementTagNameMap` | No | - | HTML tag for the wrapper element |
+| `jss` | `JSS` | No | - | Custom styles for the wrapper |
+
+---
+
+## Basic usage
+
+Wrap any element with `Tooltip` to show contextual information on hover:
+
+<Row gap="large" padding="xlarge">
+  <Tooltip content="This confirms the action">
+    <Button bare color="positive" onClick={() => {}}>
+      Hover me
+    </Button>
+  </Tooltip>
+</Row>
+
+```js
+<Tooltip content="This confirms the action">
+  <Button bare color="positive" onClick={() => {}}>
+    Hover me
+  </Button>
 </Tooltip>
+```
+
+---
+
+## With IconButton
+
+Tooltips are especially useful with icon-only buttons to explain their purpose:
+
+<Row gap="large" padding="xlarge">
+  <Tooltip content="Save document">
+    <IconButton bare icon="fa-save" size="medium" color="secondary" onClick={() => {}} />
+  </Tooltip>
+  <Tooltip content="Print document">
+    <IconButton bare icon="fa-print" size="medium" color="secondary" onClick={() => {}} />
+  </Tooltip>
+  <Tooltip content="Share with others">
+    <IconButton bare icon="fa-share" size="medium" color="secondary" onClick={() => {}} />
+  </Tooltip>
+</Row>
 
 ```js
-<Tooltip content="Tooltip here">
-  <Button
+<Tooltip content="Save document">
+  <IconButton
     bare
-    label="Hover to show tooltip"
-    color="positive"
+    icon="fa-save"
+    size="medium"
+    color="secondary"
     onClick={() => {}}
   />
 </Tooltip>
 ```
 
 ---
+
+## Behavior
+
+- **Shows on hover**: Tooltip appears when mouse enters the wrapped element
+- **Hides on leave**: Tooltip disappears when mouse leaves
+- **Keyboard dismissal**: Pressing Escape or Tab closes the tooltip
+- **Click dismissal**: Clicking anywhere closes the tooltip
+
+---
+
+## Accessibility considerations
+
+Tooltips should contain only supplementary information:
+
+- **Do**: Use for hints, descriptions, or labels
+- **Don't**: Put interactive elements (buttons, links) inside tooltips
+- **Don't**: Put essential information only in tooltips
+
+For interactive floating content, use `Popover` instead.
+
+```js
+// Good - informational tooltip
+<Tooltip content="Keyboard shortcut: Ctrl+S">
+  <Button color="primary" onClick={save}>Save</Button>
+</Tooltip>
+
+// Bad - essential information hidden
+<Tooltip content="Click here to delete your account permanently">
+  <Button color="negative" onClick={delete}>Delete</Button>
+</Tooltip>
+```
+
+---
+
+## Tooltip vs Popover
+
+| Use Tooltip | Use Popover |
+|-------------|-------------|
+| Simple text hints | Interactive content |
+| Non-essential information | Menus, forms, selections |
+| Keyboard shortcuts | Actions requiring user input |
+| Brief descriptions | Multi-step interactions |