aidos-ui 4.0.0 → 4.0.2

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

package/src/pages/FlexLayout.mdx

@@ -1,77 +1,211 @@
 import { Column } from "../Column";
 import { Row } from "../Row";
 import { Badge } from "../Badge";
+import { BaseView } from "../BaseView";
+import { Span } from "../Text";
 import { cssVar } from "../jss";
 
 # FlexLayout
 
-Because flex is so common there are a `Row` and a `Column` components, with a lot of utility that mean it is very easy to create complex layouts without having to create extra styles.
+`Row` and `Column` are the primary layout components, providing a simple API for flexbox layouts without writing custom styles.
 
-- justify: like the `justify-content` flex property.
-- gap: like the `gap` property, it accepts any `Size`.
-- align: like the `align-items` flex property.
-- padding: like the `padding` property, it accepts any `Padding`.
+---
+
+## Row
+
+Arranges children horizontally (flex-direction: row).
+
+<Row gap="medium" padding="medium" jss={{ border: `1px solid ${cssVar("--divider")}`, borderRadius: 8 }}>
+  <Badge />
+  <Badge />
+  <Badge />
+</Row>
+
+```js
+<Row gap="medium" padding="medium">
+  <Badge />
+  <Badge />
+  <Badge />
+</Row>
+```
+
+---
+
+## Column
+
+Arranges children vertically (flex-direction: column).
+
+<Column gap="medium" padding="medium" jss={{ border: `1px solid ${cssVar("--divider")}`, borderRadius: 8 }}>
+  <Badge />
+  <Badge />
+  <Badge />
+</Column>
+
+```js
+<Column gap="medium" padding="medium">
+  <Badge />
+  <Badge />
+  <Badge />
+</Column>
+```
+
+---
+
+## Props
+
+Both `Row` and `Column` accept the same props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `gap` | `Gap` | - | Space between children: `"none"`, `"xsmall"`, `"small"`, `"medium"`, `"large"`, `"xlarge"` |
+| `padding` | `Padding` | - | Internal padding (same values as gap) |
+| `justify` | `Justify` | - | Main axis alignment: `"start"`, `"end"`, `"center"`, `"space-between"`, `"space-around"`, `"space-evenly"` |
+| `align` | `Align` | - | Cross axis alignment: `"start"`, `"end"`, `"center"`, `"stretch"`, `"baseline"` |
+| `grow` | `boolean` | `false` | Allow element to grow (flex-grow: 1) |
+| `shrink` | `boolean` | `false` | Allow element to shrink (flex-shrink: 1) |
+| `wrap` | `boolean` | `false` | Allow items to wrap |
+
+---
+
+## Justify content
+
+Control how items are distributed along the main axis:
 
 <Column gap="medium">
-  <Row
-    jss={{ border: `1px solid ${cssVar("--highlight")}` }}
-    justify="space-around"
-    align="center"
-  >
-    <Badge />
-    <Badge />
-    <Badge />
+  <Row justify="start" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}` }}>
+    <Badge /><Badge /><Badge />
   </Row>
-  <Row
-    jss={{ border: `1px solid ${cssVar("--highlight")}` }}
-    justify="space-evenly"
-    align="center"
-  >
-    <Badge />
-    <Badge />
-    <Badge />
+  <Row justify="center" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}` }}>
+    <Badge /><Badge /><Badge />
   </Row>
-  <Row
-    jss={{ border: `1px solid ${cssVar("--highlight")}` }}
-    justify="space-between"
-    align="center"
-  >
-    <Badge />
-    <Badge />
-    <Badge />
+  <Row justify="end" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row justify="space-between" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row justify="space-around" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row justify="space-evenly" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}` }}>
+    <Badge /><Badge /><Badge />
   </Row>
 </Column>
 
 ```js
-<Column gap="medium">
-  <Row
-    jss={{ border: `1px solid ${cssVar("--highlight")}` }}
-    justify="space-around"
-    align="center"
-  >
-    <Badge />
-    <Badge />
+<Row justify="start">...</Row>
+<Row justify="center">...</Row>
+<Row justify="end">...</Row>
+<Row justify="space-between">...</Row>
+<Row justify="space-around">...</Row>
+<Row justify="space-evenly">...</Row>
+```
+
+---
+
+## Align items
+
+Control how items are aligned on the cross axis:
+
+<Row gap="medium">
+  <Row align="start" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}`, height: 80 }}>
     <Badge />
   </Row>
-  <Row
-    jss={{ border: `1px solid ${cssVar("--highlight")}` }}
-    justify="space-evenly"
-    align="center"
-  >
-    <Badge />
-    <Badge />
+  <Row align="center" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}`, height: 80 }}>
     <Badge />
   </Row>
-  <Row
-    jss={{ border: `1px solid ${cssVar("--highlight")}` }}
-    justify="space-between"
-    align="center"
-  >
-    <Badge />
-    <Badge />
+  <Row align="end" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}`, height: 80 }}>
     <Badge />
   </Row>
+  <Row align="stretch" padding="small" jss={{ border: `1px solid ${cssVar("--highlight")}`, height: 80 }}>
+    <BaseView jss={{ backgroundColor: cssVar("--highlight"), width: 16 }} />
+  </Row>
+</Row>
+
+```js
+<Row align="start">...</Row>
+<Row align="center">...</Row>
+<Row align="end">...</Row>
+<Row align="stretch">...</Row>
+```
+
+---
+
+## Gap sizes
+
+<Column gap="medium">
+  <Row gap="none" jss={{ border: `1px solid ${cssVar("--divider")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row gap="small" jss={{ border: `1px solid ${cssVar("--divider")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row gap="medium" jss={{ border: `1px solid ${cssVar("--divider")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row gap="large" jss={{ border: `1px solid ${cssVar("--divider")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
+  <Row gap="xlarge" jss={{ border: `1px solid ${cssVar("--divider")}` }}>
+    <Badge /><Badge /><Badge />
+  </Row>
 </Column>
+
+```js
+<Row gap="none">...</Row>    // 0px
+<Row gap="xsmall">...</Row>  // 4px
+<Row gap="small">...</Row>   // 8px
+<Row gap="medium">...</Row>  // 12px
+<Row gap="large">...</Row>   // 16px
+<Row gap="xlarge">...</Row>  // 24px
+```
+
+---
+
+## Grow and shrink
+
+Control how items expand or contract:
+
+<Row gap="medium" jss={{ border: `1px solid ${cssVar("--divider")}` }}>
+  <BaseView padding="medium" jss={{ backgroundColor: cssVar("--highlight") }}>
+    <Span color="light">Fixed</Span>
+  </BaseView>
+  <BaseView grow padding="medium" jss={{ backgroundColor: cssVar("--secondary-background") }}>
+    <Span>Grows to fill space</Span>
+  </BaseView>
+  <BaseView padding="medium" jss={{ backgroundColor: cssVar("--highlight") }}>
+    <Span color="light">Fixed</Span>
+  </BaseView>
+</Row>
+
+```js
+<Row>
+  <BaseView>Fixed width</BaseView>
+  <BaseView grow>Fills remaining space</BaseView>
+  <BaseView>Fixed width</BaseView>
+</Row>
 ```
 
 ---
+
+## Nesting layouts
+
+Combine Row and Column for complex layouts:
+
+```js
+<Column gap="medium" padding="medium">
+  <Row justify="space-between" align="center">
+    <Span>Title</Span>
+    <Button color="primary" onClick={() => {}}>Action</Button>
+  </Row>
+  <Row gap="medium">
+    <Column grow gap="small">
+      <Span>Main content</Span>
+      <P>Description text here...</P>
+    </Column>
+    <Column gap="small">
+      <Span>Sidebar</Span>
+    </Column>
+  </Row>
+</Column>
+```

package/src/pages/Hashing.mdx

@@ -1,20 +1,211 @@
-# Hashing and unique IDs
+# Hashing and Unique IDs
+
+Utility functions for generating consistent hashes and converting numbers to different bases. Useful for creating unique identifiers, keys, and compact representations.
+
+---
 
 ## hash
 
-The `hash` function can be used to create a numeric hash from a given string. If you want to constraint the hashing space you can pass an optional modulus.
+Generates a numeric hash from a string. The hash is deterministic - the same input always produces the same output.
+
+### Signature
+
+```ts
+function hash(source: string, modulus?: number): number
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `source` | `string` | Required | The string to hash |
+| `modulus` | `number` | - | Optional modulus to constrain the hash range |
+
+### Returns
+
+A non-negative integer hash value.
+
+### Basic usage
 
 ```js
-const id = hash("ABC"); // 64578
-const small_id = hash("ABC", 10); // 8
+import { hash } from "aidos-ui";
+
+const id = hash("ABC");        // 64578
+const id2 = hash("ABC");       // 64578 (same input = same output)
+const id3 = hash("ABCD");      // Different value
 ```
 
+### With modulus
+
+Constrain the hash to a specific range:
+
+```js
+// Hash constrained to 0-9
+const small_id = hash("ABC", 10);  // 8
+
+// Hash constrained to 0-99
+const medium_id = hash("ABC", 100);  // 78
+
+// Useful for array indices
+const colors = ["red", "blue", "green", "yellow"];
+const colorIndex = hash("user123", colors.length);
+const userColor = colors[colorIndex];
+```
+
+### Use cases
+
+```js
+// Consistent avatar colors
+function getUserColor(userId) {
+  const colors = ["#FF5733", "#33FF57", "#3357FF", "#FF33F5"];
+  return colors[hash(userId, colors.length)];
+}
+
+// Cache keys
+const cacheKey = hash(JSON.stringify(params));
+
+// Partitioning
+const partition = hash(userId, 10);  // 0-9
+```
+
+---
+
 ## numberToBase
 
-The `numberToBase` util will transform any number to an arbitrary base represented as a string of characters (e.g. the base two could be ["0", "1"]). This can be useful to convert between numeric representations or to compress big numbers. It defaults to a base of 26 elements formed of the English alphabet.
+Converts a number to a string representation in an arbitrary base using custom characters.
+
+### Signature
+
+```ts
+function numberToBase(
+  value: number,
+  alphabet?: string[]
+): string
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | `number` | Required | The number to convert |
+| `alphabet` | `string[]` | `["a"-"z"]` | Characters to use for each digit |
+
+### Returns
+
+A string representation of the number in the given base.
+
+### Basic usage
 
 ```js
-const id_base_26 = numberToBase(hash("ABC")); // cqmv
-const id_base_2 = numberToBase(hash("ABC"), ["?", "!"]); //!!!!!???!???!?!
-const id_base_2 = numberToBase(8, ["1", "0"]); // 100
+import { numberToBase } from "aidos-ui";
+
+// Default: base-26 using lowercase letters
+const id = numberToBase(hash("ABC"));  // "cqmv"
+const id2 = numberToBase(12345);       // "wmt"
 ```
+
+### Custom bases
+
+```js
+// Binary (base-2)
+numberToBase(8, ["0", "1"]);           // "1000"
+
+// With custom symbols
+numberToBase(hash("ABC"), ["?", "!"]);  // "!!!!!???!???!?!"
+
+// Hexadecimal-like
+const hex = ["0", "1", "2", "3", "4", "5", "6", "7",
+             "8", "9", "a", "b", "c", "d", "e", "f"];
+numberToBase(255, hex);                 // "ff"
+
+// URL-safe characters
+const urlSafe = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789".split("");
+numberToBase(123456789, urlSafe);       // Compact URL-safe ID
+```
+
+### Combining with hash
+
+```js
+// Generate compact, unique IDs
+function generateId(input) {
+  return numberToBase(hash(input));
+}
+
+const userId = generateId("user@example.com");  // e.g., "xkcd"
+const postId = generateId("blog-post-title");   // e.g., "qwer"
+```
+
+---
+
+## Common patterns
+
+### Unique class names
+
+```js
+function uniqueClassName(styles) {
+  const styleString = JSON.stringify(styles);
+  return `_${numberToBase(hash(styleString))}`;
+}
+
+const className = uniqueClassName({ color: "red" });  // e.g., "_abc"
+```
+
+### Consistent randomization
+
+```js
+// Same input always gives same "random" result
+function pseudoRandom(seed, max) {
+  return hash(seed, max);
+}
+
+// Consistent shuffle based on seed
+function seededShuffle(array, seed) {
+  return array.slice().sort((a, b) => {
+    return hash(`${seed}-${a}`) - hash(`${seed}-${b}`);
+  });
+}
+```
+
+### Short URLs
+
+```js
+// Convert database IDs to short codes
+function toShortCode(numericId) {
+  const chars = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split("");
+  return numberToBase(numericId, chars);
+}
+
+toShortCode(123456);  // e.g., "w7e"
+```
+
+### Color from string
+
+```js
+function stringToColor(str) {
+  const h = hash(str, 360);
+  return `hsl(${h}, 70%, 50%)`;
+}
+
+stringToColor("John");   // Consistent color for "John"
+stringToColor("Jane");   // Different color for "Jane"
+```
+
+---
+
+## Algorithm details
+
+The `hash` function uses a simple but effective string hashing algorithm:
+- Iterates through each character
+- Combines character codes using bit shifting
+- Produces a 32-bit integer hash
+- Applies modulus if specified
+
+This is suitable for:
+- Generating consistent keys
+- Distributing values evenly
+- Creating pseudo-random but reproducible results
+
+Not suitable for:
+- Cryptographic purposes
+- Security-sensitive hashing
+- Password storage