@redis-ui/components 42.8.0 → 43.2.1

package/skills/redis-ui-components/references/KeyValueList.md

@@ -0,0 +1,501 @@
+# KeyValueList
+
+A table for editing key-value pairs inline. It supports row deletion, custom key/value renderers, scrolling, and a companion add-row button.
+
+## Import
+
+```tsx
+import {
+  KeyValueList,
+  KeyValuePair,
+  RowInitializers,
+  UseKeyValueListReturn,
+  useKeyValueList
+} from '@redislabsdev/redis-ui-components';
+```
+
+> Also exported: `KeyValueList.AddButton` and `KeyValueListAddButtonProps`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `KeyValuePair<TKey, TValue>[]` | - | Rows rendered by the table; each row needs a unique `id` |
+| emptyStateMessage | `string` | `'There are no tags associated with this database'` | Empty-state copy shown when `data` is empty |
+| onDelete | `(row: KeyValuePair<TKey, TValue>) => void` | - | Called when a row delete action is triggered |
+| onKeyChange | `(row: KeyValuePair<TKey, TValue>, newKey: TKey) => void` | - | Called when the key field changes for a row |
+| onValueChange | `(row: KeyValuePair<TKey, TValue>, newValue: TValue) => void` | - | Called when the value field changes for a row |
+| renderKey | `(row: KeyValuePair<TKey, TValue>) => React.ReactNode` | - | Custom renderer for the key column |
+| renderValue | `(row: KeyValuePair<TKey, TValue>) => React.ReactNode` | - | Custom renderer for the value column |
+| maxHeight | `string` | - | Max height applied to the scroll container |
+| keyPlaceholder | `string` | `'Enter key'` | Placeholder shown by the default key input |
+| valuePlaceholder | `string` | `'Enter value'` | Placeholder shown by the default value input |
+
+`KeyValueList` also extends `React.HTMLAttributes<HTMLDivElement>`.
+
+## Sub-components
+
+- `KeyValueList.AddButton` - pre-styled add-row button with optional tooltip support.
+
+### KeyValueList.AddButton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | `'Add additional tag'` | Button label |
+| tooltip | `React.ReactNode` | - | Optional tooltip content shown on hover |
+
+`KeyValueList.AddButton` also extends `React.ButtonHTMLAttributes<HTMLButtonElement>` and forwards its ref to the underlying button.
+
+## Related Types
+
+### KeyValuePair
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| key | `TKey` | - | Row key value |
+| value | `TValue` | - | Row value |
+| id | `string` | - | Stable row identifier used as the React key |
+
+### RowInitializers
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| initializeKey | `() => TKey` | - | Creates the initial key for a new row |
+| initializeValue | `() => TValue` | - | Creates the initial value for a new row |
+
+### UseKeyValueListReturn
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| data | `KeyValuePair<TKey, TValue>[]` | - | Current rows |
+| handleAdd | `() => void` | - | Adds a new row using the initializers |
+| handleDelete | `(row: KeyValuePair<TKey, TValue>) => void` | - | Removes a row |
+| handleKeyChange | `(row: KeyValuePair<TKey, TValue>, newKey: TKey) => void` | - | Updates a row key |
+| handleValueChange | `(row: KeyValuePair<TKey, TValue>, newValue: TValue) => void` | - | Updates a row value |
+| setData | `React.Dispatch<React.SetStateAction<KeyValuePair<TKey, TValue>[]>>` | - | Direct state setter for the row array |
+
+### useKeyValueList
+
+A convenience hook for managing `KeyValueList` row state.
+
+| Parameter | Type | Default | Description |
+|------|------|---------|-------------|
+| initialData | `KeyValuePair<TKey, TValue>[]` | - | Initial rows seeded into the hook |
+| initializers | `RowInitializers<TKey, TValue>` | - | Functions used when `handleAdd` creates a new row |
+
+The hook returns a `UseKeyValueListReturn<TKey, TValue>` object with `data`, `handleAdd`, `handleDelete`, `handleKeyChange`, `handleValueChange`, and `setData`.
+
+## Examples
+
+### Basic Usage
+
+> Interactive playground for KeyValueList component. Use the controls below to experiment with different props and configurations.
+
+```tsx
+import { useRef } from 'react';
+import { KeyValueList, KeyValuePair } from '@redislabsdev/redis-ui-components';
+import { useArgState } from '../../helpers/useArgState';
+import { sampleData } from './KeyValueList.data';
+
+export function Render(args) {
+  const nextIdRef = useRef(sampleData.length);
+
+  const [data, handleDelete, setData] = useArgState({
+    arg: args.data as KeyValuePair<string, string>[],
+    event: args.onDelete,
+    getNewState: (items, [row]) => items.filter((item) => item.id !== row.id)
+  });
+
+  const handleKeyChange = (row: KeyValuePair<string, string>, newKey: string) => {
+    setData((prevData) =>
+      prevData.map((item) => (item.id === row.id ? { ...item, key: newKey } : item))
+    );
+    args.onKeyChange?.(row, newKey);
+  };
+
+  const handleValueChange = (row: KeyValuePair<string, string>, newValue: string) => {
+    setData((prevData) =>
+      prevData.map((item) => (item.id === row.id ? { ...item, value: newValue } : item))
+    );
+    args.onValueChange?.(row, newValue);
+  };
+
+  const handleAdd = () => {
+    const newRow: KeyValuePair<string, string> = {
+      id: `row-${nextIdRef.current}`,
+      key: '',
+      value: ''
+    };
+    nextIdRef.current += 1;
+    setData((prevData) => [...prevData, newRow]);
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList<string, string>
+        maxHeight={args.maxHeight}
+        emptyStateMessage={args.emptyStateMessage}
+        data={data}
+        onKeyChange={handleKeyChange}
+        onValueChange={handleValueChange}
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton onClick={handleAdd} />
+    </div>
+  );
+}
+```
+
+### SimpleInput
+
+> Basic example showing KeyValueList with simple text inputs for both keys and values. This is the most common use case with default rendering.
+
+```tsx
+import { KeyValueList, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { sampleData } from './KeyValueList.data';
+
+export function Render() {
+  const { data, handleAdd, handleDelete, handleKeyChange, handleValueChange } = useKeyValueList(
+    sampleData,
+    {
+      initializeKey: () => '',
+      initializeValue: () => ''
+    }
+  );
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        onKeyChange={handleKeyChange}
+        onValueChange={handleValueChange}
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton onClick={handleAdd} />
+    </div>
+  );
+}
+```
+
+### EmptyState
+
+> Demonstrates the default empty state when no data is present. The component displays a default message prompting users to add their first row.
+
+```tsx
+import { KeyValueList, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { emptyData } from './KeyValueList.data';
+
+export function Render() {
+  const { data, handleAdd, handleDelete } = useKeyValueList(emptyData, {
+    initializeKey: () => '',
+    initializeValue: () => ''
+  });
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList data={data} onDelete={handleDelete} />
+      <KeyValueList.AddButton onClick={handleAdd} />
+    </div>
+  );
+}
+```
+
+### CustomEmptyState
+
+> Shows how to customize the empty state message using the `emptyStateMessage` prop. You can also customize the AddButton text to match your use case.
+
+```tsx
+import { KeyValueList, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { emptyData } from './KeyValueList.data';
+
+export function Render() {
+  const { data, handleAdd, handleDelete } = useKeyValueList(emptyData, {
+    initializeKey: () => '',
+    initializeValue: () => ''
+  });
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        emptyStateMessage="🏷️ No labels found. Start by adding your first label!"
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton onClick={handleAdd}>Add new label</KeyValueList.AddButton>
+    </div>
+  );
+}
+```
+
+### WithDropdown
+
+> Demonstrates using a dropdown (Select) for keys with predefined options. Use the `renderKey` prop to provide custom rendering for the key column.
+
+```tsx
+import { KeyValueList, KeyValuePair, Select, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { keyOptions, sampleData } from './KeyValueList.data';
+
+const renderKeyWithDropdown = (
+  row: KeyValuePair<string, string>,
+  handleKeyChange: (row: KeyValuePair<string, string>, newKey: string) => void
+) => (
+  <Select
+    options={keyOptions}
+    value={row.key}
+    onChange={(newKey) => handleKeyChange(row, newKey)}
+    placeholder="Select key"
+  />
+);
+
+export function Render() {
+  const { data, handleAdd, handleDelete, handleKeyChange, handleValueChange } = useKeyValueList(
+    sampleData,
+    {
+      initializeKey: () => '',
+      initializeValue: () => ''
+    }
+  );
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        renderKey={(row) => renderKeyWithDropdown(row, handleKeyChange)}
+        onValueChange={handleValueChange}
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton onClick={handleAdd} />
+    </div>
+  );
+}
+```
+
+### WithSuggestions
+
+> Shows how to use AutoCompleteSelect for values with suggestions. Users can select from predefined options or enter custom values. Use the `renderValue` prop for custom value rendering.
+
+```tsx
+import { AutoCompleteSelect, KeyValueList, KeyValuePair, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { suggestionOptions, sampleData } from './KeyValueList.data';
+
+const renderValueWithSuggestions = (
+  row: KeyValuePair<string, string>,
+  handleValueChange: (row: KeyValuePair<string, string>, newValue: string) => void
+) => (
+  <AutoCompleteSelect
+    options={suggestionOptions}
+    value={row.value}
+    onChange={(newValue) => handleValueChange(row, newValue)}
+    placeholder="Select or type value"
+    manualOptionText="Use custom value"
+    optionsLabel="Suggestions"
+  />
+);
+
+export function Render() {
+  const { data, handleAdd, handleDelete, handleKeyChange, handleValueChange } = useKeyValueList(
+    sampleData,
+    {
+      initializeKey: () => '',
+      initializeValue: () => ''
+    }
+  );
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        onKeyChange={handleKeyChange}
+        renderValue={(row) => renderValueWithSuggestions(row, handleValueChange)}
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton onClick={handleAdd} />
+    </div>
+  );
+}
+```
+
+### WithMaxHeightAndMaxRows
+
+> Demonstrates using `maxHeight` prop to control table scrolling and implementing a maximum row limit. The AddButton shows a tooltip when the maximum is reached using the `disabled` and `tooltip` props.
+
+```tsx
+import { KeyValueList, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { largeData } from './KeyValueList.data';
+
+export function Render() {
+  const maxRows = 10;
+  const { data, handleAdd, handleDelete, handleKeyChange, handleValueChange } = useKeyValueList(
+    largeData.slice(0, 8),
+    {
+      initializeKey: () => '',
+      initializeValue: () => ''
+    }
+  );
+
+  const isMaxReached = data.length >= maxRows;
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        maxHeight="200px"
+        onKeyChange={handleKeyChange}
+        onValueChange={handleValueChange}
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton
+        onClick={handleAdd}
+        disabled={isMaxReached}
+        tooltip={isMaxReached ? 'Maximum of 10 rows reached' : undefined}
+      />
+    </div>
+  );
+}
+```
+
+### WithKeyValidation
+
+> Example showing how to implement validation for keys using the `renderKey` prop with custom Input components. This demonstrates required field validation, format validation, and uniqueness checks.
+
+```tsx
+import { useState } from 'react';
+import { Input, KeyValueList, KeyValuePair, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { sampleData } from './KeyValueList.data';
+
+const renderKeyWithValidation = (
+  row: KeyValuePair<string, string>,
+  options: {
+    touchedFields: Set<string>;
+    validateKey: (key: string) => string | undefined;
+    handleKeyChange: (row: KeyValuePair<string, string>, newKey: string) => void;
+    handleFieldTouch: (rowId: string) => void;
+  }
+) => {
+  const { touchedFields, validateKey, handleKeyChange, handleFieldTouch } = options;
+  const isTouched = touchedFields.has(row.id);
+  const errorMessage = isTouched ? validateKey(row.key) : undefined;
+
+  return (
+    <Input
+      value={row.key}
+      onChange={(newKey) => handleKeyChange(row, newKey)}
+      onBlur={() => handleFieldTouch(row.id)}
+      placeholder="Enter key"
+      error={errorMessage}
+    />
+  );
+};
+
+export function Render() {
+  const [touchedFields, setTouchedFields] = useState<Set<string>>(new Set());
+  const { data, handleAdd, handleDelete, handleKeyChange, handleValueChange } = useKeyValueList(
+    sampleData,
+    {
+      initializeKey: () => '',
+      initializeValue: () => ''
+    }
+  );
+
+  const validateKey = (key: string): string | undefined => {
+    if (!key || key.trim() === '') {
+      return 'Key is required';
+    }
+
+    if (key.includes(' ')) {
+      return 'Key cannot contain spaces';
+    }
+
+    const duplicateCount = data.filter((item) => item.key === key).length;
+
+    if (duplicateCount > 1) {
+      return 'Key must be unique';
+    }
+
+    return undefined;
+  };
+
+  const handleFieldTouch = (rowId: string) => {
+    setTouchedFields((prev) => new Set(prev).add(rowId));
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        renderKey={(row) =>
+          renderKeyWithValidation(row, {
+            touchedFields,
+            validateKey,
+            handleKeyChange,
+            handleFieldTouch
+          })
+        }
+        onValueChange={handleValueChange}
+        onDelete={handleDelete}
+      />
+      <KeyValueList.AddButton onClick={handleAdd} />
+    </div>
+  );
+}
+```
+
+### WithCustomAddButton
+
+> Shows how to implement a completely custom add button instead of using `KeyValueList.AddButton`. You can use any button component and add custom UI elements like row counters, multiple buttons, or custom styling.
+
+```tsx
+import { Button, KeyValueList, Tooltip, useKeyValueList } from '@redislabsdev/redis-ui-components';
+import { PlusIcon } from '@redislabsdev/redis-ui-icons';
+import { sampleData } from './KeyValueList.data';
+
+export function Render() {
+  const maxRows = 5;
+  const { data, handleAdd, handleDelete, handleKeyChange, handleValueChange } = useKeyValueList(
+    sampleData,
+    {
+      initializeKey: () => '',
+      initializeValue: () => ''
+    }
+  );
+
+  const isMaxReached = data.length >= maxRows;
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.6rem' }}>
+      <KeyValueList
+        data={data}
+        onKeyChange={handleKeyChange}
+        onValueChange={handleValueChange}
+        onDelete={handleDelete}
+      />
+
+      <div style={{ display: 'flex', gap: '1.2rem', alignItems: 'center' }}>
+        <Tooltip content={isMaxReached ? `Maximum of ${maxRows} rows reached` : undefined}>
+          <Button size="medium" variant="primary" onClick={handleAdd} disabled={isMaxReached}>
+            <Button.Icon icon={PlusIcon} />
+            Add Custom Row
+          </Button>
+        </Tooltip>
+        <span style={{ fontSize: '1.4rem', color: '#666' }}>
+          {data.length} / {maxRows} rows
+        </span>
+      </div>
+    </div>
+  );
+}
+```
+
+## Notes
+
+- `Playground` is an interactive playground for experimenting with different props and configurations.
+- `SimpleInput` is the default editing flow with plain `Input` fields.
+- `EmptyState` shows the default empty-state copy when no rows exist.
+- `CustomEmptyState` shows how to override the empty-state message and the add-button label.
+- `WithDropdown` uses `renderKey` to swap the key cell for `Select`.
+- `WithSuggestions` uses `renderValue` to swap the value cell for `AutoCompleteSelect`.
+- `WithMaxHeightAndMaxRows` demonstrates `maxHeight` plus a disabled add button with tooltip when the maximum row count is reached.
+- `WithKeyValidation` shows required, format, and uniqueness validation via `renderKey`.
+- `WithCustomAddButton` shows how to replace `KeyValueList.AddButton` with fully custom button UI.
+- `KeyValueList.AddButton` supports optional tooltip content and forwards refs to the underlying button.
+- The default empty-state message is `There are no tags associated with this database`.