aidos-ui 4.0.0 → 4.0.1

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