@neo4j-ndl/react 4.16.8 → 4.16.9

package/skills/ndl-react/components/ai/suggestion.md

@@ -0,0 +1,84 @@
+# Suggestion
+
+Import: `import { Suggestion } from '@neo4j-ndl/react/ai'`
+
+## Props
+
+### Suggestion
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  | The content of the suggestion |
+| `isPrimary` | `boolean` |  |  | Whether the suggestion is primary. Renders an animated border. |
+| `leadingVisual` | `ReactNode` |  |  | The visual to display before the content. Should be an icon. |
+| `onClick` | `((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` |  |  | Callback function triggered when the suggestion is clicked |
+| `ref` | `Ref<HTMLButtonElement>` |  |  | A ref to apply to the root element. |
+| `size` | `'large' \| 'small'` |  | `small` | The size of the suggestion |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Suggestion } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return <Suggestion>How do I get started with Aura?</Suggestion>;
+};
+
+export default Component;
+```
+
+### Icon
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Suggestion } from '@neo4j-ndl/react/ai';
+import { MagnifyingGlassIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <Suggestion size="small" leadingVisual={<MagnifyingGlassIconOutline />}>
+      How do I get started with Aura?
+    </Suggestion>
+  );
+};
+
+export default Component;
+```
+
+### Primary
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Suggestion } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return <Suggestion isPrimary>How do I get started with Aura?</Suggestion>;
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Suggestion } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-row n-gap-token-8">
+      <Suggestion size="small">This is a small suggestion</Suggestion>
+      <Suggestion size="large">This is a large suggestion</Suggestion>
+    </div>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/ai/thinking.md

@@ -0,0 +1,43 @@
+# Thinking
+
+Import: `import { Thinking } from '@neo4j-ndl/react/ai'`
+
+## Props
+
+### Thinking
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `isThinking` | `boolean` |  | `true` | Whether the AI is thinking. If true, will render a thinking presence icon and the text "Thinking". If false, will render the duration of the thinking. |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+| `thinkingMs` | `number` |  | `1000` | The duration of the thinking in milliseconds |
+
+## Examples
+
+### Ai Thinking Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Thinking } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return <Thinking isThinking={true} thinkingMs={1400} />;
+};
+
+export default Component;
+```
+
+### Ai Thinking Finished
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Thinking } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return <Thinking isThinking={false} thinkingMs={1400} />;
+};
+
+export default Component;
+```

package/skills/ndl-react/components/ai/tool-call.md

@@ -0,0 +1,43 @@
+# ToolCall
+
+Import: `import { ToolCall } from '@neo4j-ndl/react/ai'`
+
+## Props
+
+### ToolCall
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` |  |  | The content of the suggestion |
+| `isDone` | `boolean` |  | `false` | Whether the AI is done with using the tool |
+| `ref` | `Ref<HTMLSpanElement>` |  |  | A ref to apply to the root element. |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ToolCall } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return <ToolCall>list_import_jobs</ToolCall>;
+};
+
+export default Component;
+```
+
+### Done
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { ToolCall } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return <ToolCall isDone>list_import_jobs</ToolCall>;
+};
+
+export default Component;
+```

package/skills/ndl-react/components/ai/user-bubble.md

@@ -0,0 +1,187 @@
+# UserBubbleComponent
+
+Import: `import { UserBubbleComponent } from '@neo4j-ndl/react/ai'`
+
+## Props
+
+### UserBubbleComponent
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `avatarProps` | `PolymorphicCommonProps<ElementType<any, keyof IntrinsicElements>, AvatarProps>` |  |  | The props for the avatar |
+| `children` | `ReactNode` |  |  | The content of the user bubble |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+| `trailingElement` | `ReactNode` |  |  | The element to display after the content. Could be a CleanIconButton to edit the user bubble. |
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { UserBubble } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return (
+    <UserBubble
+      avatarProps={{
+        name: 'KM',
+        source:
+          'https://media.istockphoto.com/id/1334716681/photo/a-smiling-man.jpg?s=612x612&w=0&k=20&c=U6rkSDpQMzkcJEqx2hAa63fNLIhqnZb31Xuc_QSi648=',
+        type: 'image',
+      }}
+    >
+      Can you analyse my data and tell me about...?
+    </UserBubble>
+  );
+};
+
+export default Component;
+```
+
+### Action
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { CleanIconButton } from '@neo4j-ndl/react';
+import { UserBubble } from '@neo4j-ndl/react/ai';
+import { PencilSquareIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <UserBubble
+      avatarProps={{
+        name: 'KM',
+        type: 'letters',
+      }}
+      trailingElement={
+        <CleanIconButton description="Edit" size="large">
+          <PencilSquareIconOutline />
+        </CleanIconButton>
+      }
+    >
+      Can you analyse my data and tell me about...?
+    </UserBubble>
+  );
+};
+
+export default Component;
+```
+
+### And Files
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Menu } from '@neo4j-ndl/react';
+import { FileTag, ImageTag, MoreFiles, UserBubble } from '@neo4j-ndl/react/ai';
+import {
+  DocumentIconOutline,
+  PhotoIconOutline,
+  TableCellsIconOutline,
+} from '@neo4j-ndl/react/icons';
+import { useRef, useState } from 'react';
+
+const Component = () => {
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const anchorRef = useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <div className="n-flex n-flex-coln-gap-token-64 n-w-full n-justify-end">
+      <div className="n-flex n-flex-col n-gap-token-8 n-items-end">
+        <MoreFiles
+          count={3}
+          isActive={isMenuOpen}
+          onClick={() => setIsMenuOpen(!isMenuOpen)}
+          ref={anchorRef}
+        />
+        <Menu
+          isOpen={isMenuOpen}
+          anchorRef={anchorRef}
+          onClose={() => setIsMenuOpen(false)}
+        >
+          <Menu.Item
+            leadingVisual={<DocumentIconOutline />}
+            title="Gardening tips"
+            description="PDF"
+            onClick={() => alert('Gardening tips')}
+          />
+          <Menu.Item
+            leadingVisual={<TableCellsIconOutline />}
+            title="TvSeries"
+            description="CSV"
+            onClick={() => alert('TvSeries')}
+          />
+          <Menu.Item
+            leadingVisual={<PhotoIconOutline />}
+            title="Family photo"
+            description="JPG"
+            onClick={() => alert('Family photo')}
+          />
+        </Menu>
+        <ImageTag
+          src="https://plus.unsplash.com/premium_photo-1676496046182-356a6a0ed002?q=80&w=2952&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
+          alt="Landscape image"
+          fileName="Landscape image"
+          fileType="jpg"
+        />
+        <FileTag
+          icon={<TableCellsIconOutline />}
+          fileName="MoviesDecade"
+          fileType="csv"
+        />
+        <FileTag
+          icon={<DocumentIconOutline />}
+          fileName="Science Fiction Bestsellers"
+          fileType="pdf"
+        />
+        <UserBubble
+          avatarProps={{
+            name: 'KM',
+            source:
+              'https://media.istockphoto.com/id/1334716681/photo/a-smiling-man.jpg?s=612x612&w=0&k=20&c=U6rkSDpQMzkcJEqx2hAa63fNLIhqnZb31Xuc_QSi648=',
+            type: 'image',
+          }}
+        >
+          Can you analyse my data and tell me about...?
+        </UserBubble>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Long
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { UserBubble } from '@neo4j-ndl/react/ai';
+
+const Component = () => {
+  return (
+    <UserBubble
+      avatarProps={{
+        name: 'KM',
+        type: 'letters',
+      }}
+    >
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed in rutrum
+      massa, ut congue nisi. Curabitur pulvinar odio id eros ornare dictum.
+      Aliquam faucibus dui ligula, ac gravida enim mattis at. Proin pretium
+      massa a risus eleifend consectetur. Fusce auctor maximus tellus sed
+      lobortis. Nulla congue leo posuere ante accumsan, vel maximus justo
+      cursus. Sed cursus varius ante at scelerisque. Fusce non venenatis diam.
+      Nam sed dolor ultricies, varius sem sed, vulputate felis. Ut facilisis
+      efficitur sem, et laoreet neque. Fusce congue vulputate magna. Mauris
+      euismod egestas imperdiet. Sed mollis venenatis nunc eget laoreet.
+    </UserBubble>
+  );
+};
+
+export default Component;
+```

package/skills/ndl-react/components/avatar.md

@@ -0,0 +1,169 @@
+# Avatar
+
+Import: `import { Avatar } from '@neo4j-ndl/react'`
+
+## Props
+
+### Avatar
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `as` | `("button" & ElementType<any, keyof IntrinsicElements>) \| ("symbol" & ElementType<any, keyof IntrinsicElements>) \| ... 178 more ...` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
+| `hasStatus` | `boolean` |  | `false` | Whether to display a status indicator |
+| `icon` | `ReactNode` |  |  | Custom icon to display when `type` is `"icon"`. Defaults to `UserIconOutline` |
+| `isDisabled` | `boolean` |  | `false` | Whether the avatar is disabled. When disabled, status indicators are hidden and `onClick` handlers are disabled when cast as a button |
+| `name` | `string` |  |  | The name associated with the avatar. Used for alt text and aria-label. For letters type, this text is displayed |
+| `onClick` | `() => void` | ✅ |  |  |
+| `ref` | `any` |  |  | A ref to apply to the root element. |
+| `shape` | `'circle' \| 'square'` |  | `circle` | The shape of the avatar |
+| `size` | `'large' \| 'medium' \| 'small' \| 'x-large' \| 'x-small'` |  | `medium` | The size of the avatar |
+| `source` | `string` |  |  | Source URI for the image. When provided with `type="image`", displays the image |
+| `status` | `'offline' \| 'online' \| 'unknown'` |  |  | The status to display. Only shown when `hasStatus` is `true` and component is not disabled |
+| `type` | `'icon' \| 'image' \| 'letters'` |  | `image` | The type of avatar content. If `type="image"` and no source is provided, automatically falls back to `icon` |
+
+## Accessibility
+
+## Implementation guidelines
+
+The component has an `aria-label` set to `avatar ${name}` to provide context to screen readers. Status indicators include title attributes and proper role attributes. When displaying images, proper alt text is provided using the `name` prop.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Avatar />;
+};
+
+export default Component;
+```
+
+### Custom Icon
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+import {
+  BellIconOutline,
+  HeartIconOutline,
+  StarIconOutline,
+} from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16">
+      <Avatar type="icon" name="Favorites" icon={<StarIconOutline />} />
+      <Avatar type="icon" name="Notifications" icon={<BellIconOutline />} />
+      <Avatar type="icon" name="Likes" icon={<HeartIconOutline />} />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return <Avatar isDisabled as="button" onClick={() => alert('Clicked!')} />;
+};
+
+export default Component;
+```
+
+### Shapes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16">
+      <Avatar shape="circle" />
+      <Avatar shape="square" />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16">
+      <Avatar size="x-small" />
+      <Avatar size="small" />
+      <Avatar size="medium" />
+      <Avatar size="large" />
+      <Avatar size="x-large" />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Statuses
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16 n-items-center">
+      <Avatar hasStatus={false} />
+      <Avatar hasStatus status="online" />
+      <Avatar hasStatus status="offline" />
+      <Avatar hasStatus status="unknown" />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Types
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Avatar } from '@neo4j-ndl/react';
+
+const Component = () => {
+  return (
+    <div className="n-flex n-gap-token-16">
+      <Avatar type="icon" name="Karl Morrison" />
+      <Avatar type="letters" name="Karl Morrison" />
+      <Avatar
+        type="image"
+        name="Karl Morrison"
+        source="https://media.istockphoto.com/id/1334716681/photo/a-smiling-man.jpg?s=612x612&w=0&k=20&c=U6rkSDpQMzkcJEqx2hAa63fNLIhqnZb31Xuc_QSi648="
+      />
+    </div>
+  );
+};
+
+export default Component;
+```