aidos-ui 4.0.0 → 4.0.1

package/src/pages/_app.tsx

@@ -33,14 +33,22 @@ import { Column } from "../Column";
 import { Icon } from "../Icon";
 import { BaseLinkComponentOverrideContext } from "../BaseLink";
 import { DocsMDXProvider, labelToID } from "../docs/mdx";
-import { Pipeline, dot, pipeline } from "@xenova/transformers";
+import type { Pipeline } from "@xenova/transformers";
 import { pages } from "../docs/pages";
 
 import { Inter } from "next/font/google";
 
 const inter = Inter({ subsets: ["latin"] });
 
-const transformers = import("@xenova/transformers");
+let transformersPromise: Promise<typeof import("@xenova/transformers")> | null =
+  null;
+const getTransformers = () => {
+  if (!transformersPromise) {
+    transformersPromise = import("@xenova/transformers");
+  }
+  return transformersPromise;
+};
+
 const searchIndex = import("../docs/searchIndex").then(
   (module) => module.index
 );
@@ -170,6 +178,8 @@ export default function App({ Component, pageProps }: AppProps) {
         return;
       }
 
+      const { dot } = await getTransformers();
+
       const queryEmbeddings = await generateEmbeddings(query, {
         normalize: true,
         pooling: "mean",
@@ -446,7 +456,7 @@ export default function App({ Component, pageProps }: AppProps) {
 let modelPromise: Promise<Pipeline> | null = null;
 
 const loadModel: () => Promise<Pipeline> = async () => {
-  const { pipeline } = await transformers;
+  const { pipeline } = await getTransformers();
   if (modelPromise == null) {
     modelPromise = pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
   }

package/src/pages/css-in-js.mdx

@@ -1,127 +1,240 @@
 import { Button } from "../Button";
 import { Row } from "../Row";
-import { cssVar } from "../jss";
+import { Column } from "../Column";
+import { BaseView } from "../BaseView";
+import { Span } from "../Text";
+import { cssVar, mobile, tablet } from "../jss";
 
 # CSS in JS
 
-Aidos UI has a mechanism to do css in js, which, for lack of a better name, is called `jss`, which is the name of the only function that is needed. The idea is similar to other css in js frameworks: colocation is nice, adding javascrip features to CSS solves many of the problems CSS has.
+Aidos UI uses a custom CSS-in-JS system called `jss`. Every component accepts a `jss` prop for styling, and the library includes utilities for theming, responsive design, and type-safe CSS variables.
 
-## How it works
+---
+
+## The jss prop
 
-The way the library works looks similar to inline styles:
+All components accept a `jss` prop that works like inline styles but with additional capabilities:
 
 ```js
-<div className={jss({ background: "red", padding: 12 })} />
+<BaseView jss={{ backgroundColor: "red", padding: 12 }} />
 ```
 
-Internally what is happening is that each property gets atomized into a single CSS classname with a unique hash that gets re-used.
+Internally, each property becomes an atomic CSS class with a deterministic hash, enabling server-side rendering and hydration:
 
 ```html
 <style>
-  .x1uc1pme {
-    background: red;
-  }
-
-  .x1kbdebd {
-    padding: 12;
-  }
+  .x1uc1pme { background: red; }
+  .x1kbdebd { padding: 12px; }
 </style>
 <div class="x1uc1pme x1kbdebd" />
 ```
 
-The CSS class name is a hash based on each key-pair. This makes it deterministic, which enables for this system to work with server rendered hydrated react.
+---
 
-## Selectors
+## Arrays and conditionals
 
-Because of how this system works not all selectors can be written, but this is a good thing because arguably CSS selectors are so powerful that it is very easy to make something too hard to understand. These are some examples of how selectors are generated:
+The `jss` prop accepts arrays and falsy values for conditional styling:
 
 ```js
-jss({[':hover']: { background: 'blue' }})
-.x1uc1pme:hover {
-  background: blue;
-}
+<BaseView
+  jss={[
+    { padding: 16 },
+    isActive && { backgroundColor: "blue" },
+    isDisabled && { opacity: 0.5 },
+  ]}
+/>
 ```
 
+---
+
+## Automatic pixel conversion
+
+Numeric values are automatically converted to pixels for dimensional properties:
+
 ```js
-jss({[':first-child']: { background: 'blue' }})
-.x1uc1pme:first-child {
-  background: blue;
-}
+<BaseView jss={{ padding: 16, fontSize: 14, opacity: 0.5 }} />
+// Results in: padding: 16px; font-size: 14px; opacity: 0.5;
 ```
 
+---
+
+## Pseudo-selectors
+
+Use string keys for pseudo-classes and pseudo-elements:
+
 ```js
-jss({[' div']: { background: 'blue' }})
-.x1uc1pme div {
-  background: blue;
-}
+// Hover state
+jss({ ":hover": { backgroundColor: "blue" } })
+
+// Focus state
+jss({ ":focus": { outline: "2px solid blue" } })
+
+// First child
+jss({ ":first-child": { marginTop: 0 } })
 ```
 
+---
+
+## Descendant selectors
+
+Target child elements with space-prefixed selectors:
+
 ```js
-jss({['@media (min-width: 750px)']: { maxWidth: 750 }})
-@media (min-width: 750px) .x1uc1pme {
-  maxWidth: 750
-}
+// All child divs
+jss({ " div": { padding: 8 } })
+
+// Direct children
+jss({ " > span": { color: "red" } })
 ```
 
+---
+
+## Media queries
+
+Use media query strings as keys:
+
+```js
+jss({
+  padding: 8,
+  "@media (min-width: 750px)": {
+    padding: 16,
+  },
+})
+```
+
+---
+
+## Responsive helpers
+
+The library provides helper functions for common breakpoints:
+
+```js
+import { mobile, tablet, laptop, desktop } from "aidos-ui";
+
+<BaseView
+  jss={[
+    { padding: 8 },
+    tablet({ padding: 16 }),
+    desktop({ padding: 24 }),
+  ]}
+/>
+```
+
+| Helper | Breakpoint |
+|--------|------------|
+| `mobile()` | max-width: 479px |
+| `tablet()` | min-width: 480px |
+| `laptop()` | min-width: 1024px |
+| `desktop()` | min-width: 1280px |
+
+---
+
 ## CSS variables
 
-Aidos UI comes with two default themes that can be overridden. These come with the following css variables that can be safely used (in typescript) with the `cssVar` utility:
-
-- `--overlay-background`
-- `--primary-background`
-- `--secondary-background`
-- `--divider`
-- `--strong-divider`
-- `--pressed-background`
-- `--hovered-background`
-- `--selected-background`
-- `--nav-bar`
-- `--warning`
-- `--highlight`
-- `--outline`
-- `--light-highlight`
-- `--primary-text`
-- `--secondary-text`
-- `--subtle-text`
-- `--highlight-text`
-- `--negative-text`
-- `--light-text`
-- `--background-button-positive`
-- `--background-button-secondary`
-- `--background-button-negative`
-- `--background-button-disabled`
-- `--spacing-xs`
-- `--spacing-s`
-- `--spacing-m`
-- `--spacing-l`
-- `--spacing-xl`
-- `--spacing-xxl`
-- `--spacing-xxxl`
-- `--border-radius-s`
-- `--border-radius-m`
-- `--border-radius-l`
-- `--nav-bar-height`
-
-For example:
-
-<Row justify="center">
+Use the `cssVar()` helper for type-safe access to theme variables:
+
+<Row justify="center" padding="medium">
   <Button
-    jss={{ border: `10px solid ${cssVar("--warning")}` }}
-    label="Hello"
+    jss={{ border: `4px solid ${cssVar("--warning")}` }}
     color="positive"
     onClick={() => {}}
-  />
+  >
+    Styled button
+  </Button>
 </Row>
 
 ```js
-<Row justify="center">
-  <Button
-    jss={{ border: `10px solid ${cssVar("--warning")}` }}
-    label="Hello"
-    color="positive"
-    onClick={() => {}}
-  />
-</Row>
+import { cssVar } from "aidos-ui";
+
+<BaseView jss={{
+  backgroundColor: cssVar("--primary-background"),
+  color: cssVar("--primary-text"),
+  padding: cssVar("--spacing-m"),
+}} />
 ```
 
 ---
+
+## Available CSS variables
+
+### Colors
+
+| Variable | Purpose |
+|----------|---------|
+| `--primary-background` | Main background |
+| `--secondary-background` | Alternate background |
+| `--overlay-background` | Modal/popover background |
+| `--divider` | Border/divider color |
+| `--highlight` | Accent/brand color |
+| `--warning` | Warning indicator |
+
+### Text colors
+
+| Variable | Purpose |
+|----------|---------|
+| `--primary-text` | Main text |
+| `--secondary-text` | Supporting text |
+| `--subtle-text` | Muted/disabled text |
+| `--highlight-text` | Accent text |
+| `--negative-text` | Error/destructive text |
+| `--light-text` | Text on dark backgrounds |
+
+### Interactive states
+
+| Variable | Purpose |
+|----------|---------|
+| `--hovered-background` | Hover state |
+| `--pressed-background` | Active/pressed state |
+| `--selected-background` | Selected item |
+
+### Button backgrounds
+
+| Variable | Purpose |
+|----------|---------|
+| `--background-button-positive` | Positive action buttons |
+| `--background-button-secondary` | Secondary buttons |
+| `--background-button-negative` | Destructive buttons |
+| `--background-button-disabled` | Disabled buttons |
+
+### Spacing
+
+| Variable | Size |
+|----------|------|
+| `--spacing-xs` | 4px |
+| `--spacing-s` | 8px |
+| `--spacing-m` | 12px |
+| `--spacing-l` | 16px |
+| `--spacing-xl` | 24px |
+| `--spacing-xxl` | 32px |
+| `--spacing-xxxl` | 48px |
+
+### Border radius
+
+| Variable | Size |
+|----------|------|
+| `--border-radius-s` | 4px |
+| `--border-radius-m` | 8px |
+| `--border-radius-l` | 12px |
+
+---
+
+## Using toClassnames directly
+
+For custom components, use `toClassnames()` to convert style objects to class names:
+
+```js
+import { toClassnames } from "aidos-ui";
+
+function CustomComponent({ active }) {
+  return (
+    <div
+      className={toClassnames([
+        { padding: 16, borderRadius: 8 },
+        active && { backgroundColor: "blue" },
+      ])}
+    >
+      Content
+    </div>
+  );
+}
+```

package/src/pages/navigation.mdx

@@ -1,9 +1,15 @@
 import { List } from "../List";
 import { ListButtonItem } from "../ListButtonItem";
 
-## List navigation
+# List Navigation
 
-Lists support keyboard navigation by default via the `useNavigation` hook. It can be disabled by passing the prop `navigation` and tries to emulate the [grid layout spec](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/layout-grids/):
+Lists support built-in keyboard navigation using the `useNavigation` hook. This creates an accessible, keyboard-friendly experience following WAI-ARIA patterns.
+
+---
+
+## Enabling navigation
+
+Use the `navigation` prop to enable or disable keyboard navigation:
 
 <List ariaLabel="example" navigation={true}>
   <ListButtonItem color="secondary" headline="Headline 1" onClick={() => {}} />
@@ -16,8 +22,20 @@ Lists support keyboard navigation by default via the `useNavigation` hook. It ca
   />
 </List>
 
+```js
+<List ariaLabel="example" navigation={true}>
+  <ListButtonItem headline="Headline 1" onClick={() => {}} />
+  <ListButtonItem headline="Headline 2" onClick={() => {}} />
+  <ListButtonItem headline="Headline 3" onClick={() => {}} />
+</List>
+```
+
 ---
 
+## Without navigation
+
+When `navigation` is `false`, each item is a separate tab stop:
+
 <List ariaLabel="example" navigation={false}>
   <ListButtonItem color="secondary" headline="Headline 1" onClick={() => {}} />
   <ListButtonItem color="secondary" headline="Headline 2" onClick={() => {}} />
@@ -30,27 +48,111 @@ Lists support keyboard navigation by default via the `useNavigation` hook. It ca
 </List>
 
 ```js
-<List ariaLabel="example" navigation={true}>
-  <ListButtonItem color="secondary" headline="Headline 1" onClick={() => {}} />
-  <ListButtonItem color="secondary" headline="Headline 2" onClick={() => {}} />
-  <ListButtonItem
-    withDivider={false}
-    color="secondary"
-    headline="Headline 3"
-    onClick={() => {}}
-  />
+<List ariaLabel="example" navigation={false}>
+  <ListButtonItem headline="Headline 1" onClick={() => {}} />
+  <ListButtonItem headline="Headline 2" onClick={() => {}} />
+  <ListButtonItem headline="Headline 3" onClick={() => {}} />
 </List>
+```
 
-<List ariaLabel="example" navigation={false}>
-  <ListButtonItem color="secondary" headline="Headline 1" onClick={() => {}} />
-  <ListButtonItem color="secondary" headline="Headline 2" onClick={() => {}} />
-  <ListButtonItem
-    withDivider={false}
-    color="secondary"
-    headline="Headline 3"
-    onClick={() => {}}
-  />
+---
+
+## Keyboard controls
+
+When navigation is enabled:
+
+| Key | Action |
+|-----|--------|
+| **Arrow Down** | Move to next item |
+| **Arrow Up** | Move to previous item |
+| **Arrow Right** | Move to next item |
+| **Arrow Left** | Move to previous item |
+| **Enter / Space** | Activate the focused item |
+| **Tab** | Move focus out of the list |
+
+Navigation wraps around - pressing down on the last item moves to the first.
+
+---
+
+## How it works
+
+The navigation system uses `tabIndex` management:
+
+1. **Single tab stop**: The entire list is one tab stop
+2. **Active item**: Gets `tabIndex="0"` (focusable)
+3. **Other items**: Get `tabIndex="-1"` (not in tab order)
+4. **Arrow keys**: Move the active state between items
+
+This follows the [WAI-ARIA grid layout pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/layout-grids/).
+
+---
+
+## Benefits
+
+**With navigation enabled:**
+- Faster keyboard navigation (single Tab to enter list)
+- Arrow keys to move between items
+- Better for long lists
+- More efficient for power users
+
+**With navigation disabled:**
+- Standard Tab behavior between items
+- Simpler mental model
+- Better for short lists (2-3 items)
+- Each item is independently focusable
+
+---
+
+## Accessibility considerations
+
+Always provide an `ariaLabel` for the list:
+
+```js
+<List ariaLabel="Search results" navigation={true}>
+  {/* items */}
+</List>
+
+<List ariaLabel="User menu options" navigation={true}>
+  {/* items */}
 </List>
 ```
 
+This helps screen reader users understand the list's purpose.
+
 ---
+
+## When to use navigation
+
+**Enable navigation for:**
+- Long lists (5+ items)
+- Menu-like interfaces
+- Search results
+- Option lists
+- File browsers
+
+**Disable navigation for:**
+- Short action lists (2-3 items)
+- Form field groups
+- Simple button groups
+- When each item needs independent focus
+
+---
+
+## Implementation
+
+Lists use the `useNavigation` hook internally:
+
+```js
+// Simplified internal implementation
+function List({ navigation = true, children, ariaLabel }) {
+  const rootRef = useNavigation({ enabled: navigation });
+
+  return (
+    <ul ref={rootRef} aria-label={ariaLabel}>
+      {children}
+    </ul>
+  );
+}
+```
+
+See the [useNavigation documentation](/useNavigation) for more details on the underlying hook.