@maxio-com/react-ui-components 9.21.0 → 9.22.0

package/dist/skills/maxio-react/references/components-copy-to-clipboard.md

@@ -0,0 +1,184 @@
+# CopyToClipboard
+
+## Usage Guidelines
+
+### Overview
+
+CopyToClipboard writes a value to the clipboard and confirms it, so users can take an identifier, key, or URL out of the interface without selecting text by hand. It swaps to a check mark once copied, confirms in the tooltip, and announces the result to screen readers. Place the button directly beside the value it copies. It is ghost by default, but accepts primary, secondary, and tertiary variants when more emphasis is needed.
+
+#### When to Use
+
+- Use CopyToClipboard for values users need to move elsewhere but should not have to
+  select by hand: API keys, tokens, IDs, commit SHAs, clone URLs, invoice
+  numbers.
+- Use the icon-only button inline, directly beside the value it copies. The
+  adjacent value says what will be copied and the control stays out of the way.
+
+#### When Not to Use
+
+- Do not use CopyToClipboard for actions that duplicate a record, such as
+  "Duplicate invoice". Use a [Button](components-buttons-button.md)
+  with explicit wording.
+- Do not use CopyToClipboard to copy long prose or whole page regions; let users
+  select that text themselves.
+- Do not use it as the only way to obtain a value. Keep the value visible or
+  otherwise reachable, since clipboard access can fail.
+
+### Variants
+
+| Variants           | Purpose                        | Usage notes                                                                 |
+| :----------------- | :----------------------------- | :-------------------------------------------------------------------------- |
+| Icon-only (inline) | Sits beside the value.         | `copyLabel` supplies the accessible name; the tooltip is only a hover hint. |
+| `sm` size          | Table rows and dense metadata. | Pair with `Body size="sm"` so the icon matches the line height.             |
+| `lg` size          | Larger copy actions.           | Largest target area; use where the button is not crowded by other controls. |
+
+The button is ghost by default so it does not compete with the value beside it.
+Use `variant` to increase its emphasis when needed:
+
+| `variant`   | When to use                                                    |
+| :---------- | :------------------------------------------------------------- |
+| `ghost`     | Default. Suits inline use beside the value being copied.       |
+| `tertiary`  | Use when the copy control needs slightly more emphasis.        |
+| `secondary` | Copying is one of the main actions on the surface.             |
+| `primary`   | Rare. Only when copying is _the_ action users came to perform. |
+
+### Behavior
+
+- **Mouse and touch**: pressing the button writes `value` to the clipboard and
+  the icon swaps to a check mark and the tooltip shows `copiedLabel`.
+- **Keyboard**: the button is reachable with Tab and activates with Enter or
+  Space. Focus also opens the icon-only button's tooltip.
+- **Callbacks**: a native `onClick` observes activation without replacing the
+  copy behavior. Use `onCopy` and `onCopyError` for the asynchronous result.
+- **Copied state**: reverts automatically after `resetAfterMs` (2000 ms by
+  default). Pressing again restarts the timer. Changing `value` clears feedback
+  immediately so a new value is never presented as already copied.
+- **Failure**: if the clipboard write is rejected — an insecure context, or
+  denied permission — the icon and tooltip show the failure,
+  `copyErrorLabel` is announced, and `onCopyError` fires. It never claims a copy
+  that did not happen.
+- **Async values**: keep the button `disabled` until `value` is populated so
+  users cannot copy a placeholder.
+- **Sizing**: `size` uses the shared IconButton sizing. Target areas are 28px,
+  32px, and 40px; the glyph remains 16px, consistent with
+  other icon buttons in the system.
+
+### Accessibility
+
+- The button takes its accessible name from `copyLabel`. A tooltip is
+  not an accessible name, so the label is always applied to the button itself.
+- Success and failure are announced through a `role="status"`
+  `aria-live="polite"` region rather than the tooltip, because a tooltip is not
+  announced on press and may not be open when the user activates the button by
+  keyboard.
+- The live region is rendered up front and filled after the copy, so the change
+  is announced. A region inserted together with its text is unreliable.
+- Each attempt refreshes the live region, so repeated successful copies are
+  announced as separate actions.
+- Icon changes are paired with announcement text and tooltip feedback, so
+  success and failure are never conveyed by the glyph alone.
+
+### Content
+
+- Keep `copyLabel` specific about what is copied — "Copy API key" beats "Copy"
+  when several copyable values sit near each other.
+- Keep `copiedLabel` short; it is announced verbatim.
+- Keep `copyErrorLabel` actionable and concise; "Copy failed" is the default.
+- When showing a truncated value, keep `value` set to the full string so users
+  get the complete text.
+
+### Related
+
+- **[Button](components-buttons-button.md)**: use for actions
+  that are not clipboard copies.
+- **[IconButton](components-buttons-iconbutton.md)**: use for
+  other icon-only actions; CopyToClipboard is a purpose-built wrapper around it.
+- **[TooltipTrigger](components-tooltip.md)**: supplies the hover
+  and focus hint used here.
+
+## React
+
+```tsx
+import { CopyToClipboard } from '@maxio-com/react-ui-components';
+```
+
+### Handling Failures
+
+Clipboard writes reject in insecure contexts and when the user denies
+permission. CopyToClipboard shows and announces `copyErrorLabel` in that case
+and calls `onCopyError`, so consumers can also surface application-level
+feedback when needed.
+
+```tsx
+<CopyToClipboard
+  value={apiKey}
+  copyLabel="Copy API key"
+  copyErrorLabel="API key could not be copied"
+  onCopyError={() => addToast({ sentiment: 'error', title: 'Could not copy' })}
+/>
+```
+
+### Asynchronous Values
+
+Keep the button disabled until the value exists, so users cannot copy a
+placeholder.
+
+```tsx
+<CopyToClipboard value={token ?? ''} disabled={!token} copyLabel="Copy token" />
+```
+
+## Imports
+
+```tsx
+import { Body, CopyToClipboard, Flex } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### CopyToClipboard
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `copiedLabel` | `string` | no | `Copied!` | Success feedback after a copy, shown in the tooltip and announced to screen readers. | TypeLiteral |
+| `copyErrorLabel` | `string` | no | `Copy failed` | Failure feedback after a copy, shown and announced like `copiedLabel`. | TypeLiteral |
+| `copyLabel` | `string` | no | `Copy` | Accessible name for the button, and the idle tooltip text. | TypeLiteral |
+| `disabled` | `boolean` | no | - | Prevents interaction, such as while the value is still loading. | TypeLiteral, ButtonHTMLAttributes |
+| `onCopy` | `((value: string) => void)` | no | - | Called with the copied value once the clipboard write succeeds. | TypeLiteral |
+| `onCopyError` | `((error: unknown) => void)` | no | - | Called when the clipboard write fails, such as in an insecure context or when permission is denied. The copied state is not entered. | TypeLiteral |
+| `resetAfterMs` | `number` | no | `2000` | How long the copied state lasts before reverting, in milliseconds. | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg"` | no | `md` | Changes the size of the button. | TypeLiteral |
+| `tooltipPlacement` | `"top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end"` | no | `top` | Where the tooltip is positioned relative to the button. | TypeLiteral |
+| `value` | `string` | yes | - | Text written to the clipboard when the button is pressed. | TypeLiteral |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "ghost"` | no | `ghost` | Button variant. | TypeLiteral |
+
+## Stories
+
+### Default
+
+An icon-only button sitting directly beside the value it copies. `copyLabel` carries the accessible name.
+
+```tsx
+const Default = () => <Flex alignItems="center" gap={1}>
+    <Body size="sm" as="span">
+        {args.value}
+    </Body>
+    <CopyToClipboard
+        value={API_KEY}
+        onCopy={action('Copied')}
+        onCopyError={action('Copy failed')}
+        size="sm"
+        copyLabel="Copy API key" />
+</Flex>;
+```
+
+### Disabled
+
+Disable the button while there is nothing to copy yet, such as before a generated secret has loaded.
+
+```tsx
+const Disabled = () => <CopyToClipboard
+    value={API_KEY}
+    onCopy={action('Copied')}
+    onCopyError={action('Copy failed')}
+    disabled />;
+```

package/dist/skills/maxio-react/references/components-data-table.md

@@ -243,7 +243,7 @@ import {
 | `actions` | `((row: Row<TData>, table: Table<TData>) => ReactNode)` | no | - | render custom actions cell content | TypeLiteral |
 | `actionsColumnSize` | `number` | no | - | width (in px) of the actions column; defaults to 40 | TypeLiteral |
 | `aggregationFns` | `Record<string, AggregationFn<any>>` | no | - | - | TypeLiteral |
-| `align` | `"left" \| "right"` | no | - | - | TypeLiteral |
+| `align` | `"right" \| "left"` | no | - | - | TypeLiteral |
 | `enableExpanding` | `boolean \| "rowsOnly"` | no | - | Enable nested row expansion. Include `'rowsOnly'` for row-level toggles without group expand/collapse header control. | TypeLiteral |
 | `enableRowReordering` | `boolean` | no | `false` | Enable controlled row reordering for small, non-paginated tables. Intended for approximately 100 total rows or fewer, including nested and collapsed rows. Nested row data must use the `subRows` property; custom `getSubRows` accessors are unsupported. | TypeLiteral |
 | `enableSorting` | `boolean` | no | `false` | - | TypeLiteral |

package/dist/skills/maxio-react/references/components-drawer.md

@@ -69,7 +69,7 @@ import { Body, Button, DialogTrigger, Drawer } from "@maxio-com/react-ui-compone
 | `footer` | `ReactNode` | no | - | - | DrawerProps |
 | `onOpenChange` | `((open: boolean) => void)` | no | - | - | DrawerProps |
 | `open` | `boolean` | no | - | - | DrawerProps |
-| `placement` | `"left" \| "right" \| "top" \| "bottom"` | no | `right` | - | DrawerProps |
+| `placement` | `"top" \| "right" \| "bottom" \| "left"` | no | `right` | - | DrawerProps |
 | `size` | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | no | `md` | - | DrawerProps |
 | `title` | `string` | yes | - | - | DrawerProps |
 

package/dist/skills/maxio-react/references/components-toggle.md

@@ -99,7 +99,7 @@ import { ToggleComponent } from "@maxio-com/react-ui-components";
 | `name` | `string` | no | - | Toggle name | TypeLiteral |
 | `onChange` | `((value: boolean, event?: KeyboardEvent<HTMLInputElement> \| ChangeEvent<HTMLInputElement>) => void)` | no | - | The onChange function | TypeLiteral |
 | `valueDescription` | `string` | no | - | Toggle label | TypeLiteral |
-| `valueDescriptionPosition` | `"left" \| "right"` | no | - | Toggle label position | TypeLiteral |
+| `valueDescriptionPosition` | `"right" \| "left"` | no | - | Toggle label position | TypeLiteral |
 
 ## Stories
 

package/dist/skills/maxio-react/references/components-tooltip.md

@@ -73,7 +73,7 @@ import { TooltipTrigger } from "@maxio-com/react-ui-components";
 | `isVisible` | `boolean` | no | - | Tooltip visibility state - use with useExternalState property | TypeLiteral |
 | `maxWidth` | `number \| "none"` | no | `160` | Maximum tooltip container width in pixels | TypeLiteral |
 | `onVisibilityUpdate` | `((isVisible: boolean) => void)` | no | - | Tooltip visibility state | TypeLiteral |
-| `placement` | `"left" \| "right" \| "top" \| "bottom" \| "left-start" \| "left-end" \| "right-start" \| "right-end" \| "top-start" \| "top-end" \| "bottom-start" \| "bottom-end"` | no | `right` | Overlay element placement | TypeLiteral |
+| `placement` | `"top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end"` | no | `right` | Overlay element placement | TypeLiteral |
 | `renderContent` | `() => ReactNode` | yes | - | Tooltip content renderer | TypeLiteral |
 | `size` | `"small" \| "regular"` | no | `regular` | Tooltip component size variant | TypeLiteral |
 | `usePortal` | `boolean` | no | - | Render floating element in portal container | TypeLiteral |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxio-com/react-ui-components",
-  "version": "9.21.0",
+  "version": "9.22.0",
   "description": "React UI components",
   "type": "module",
   "license": "MIT",
@@ -65,5 +65,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b9a22146235d44ea3b67a38c63bf2d6683bbef90"
+  "gitHead": "14695cb6dcb2e06f7fa85daacbffa1e502b6d7ba"
 }

package/typings/index.d.ts

@@ -1,4 +1,4 @@
-import React$1, { ReactNode, HTMLAttributes, LiHTMLAttributes, AnchorHTMLAttributes, RefObject, FC, ElementType, InputHTMLAttributes } from 'react';
+import React$1, { ReactNode, HTMLAttributes, LiHTMLAttributes, ButtonHTMLAttributes, AnchorHTMLAttributes, RefObject, FC, ElementType, InputHTMLAttributes } from 'react';
 import { RowData, Row, Table, ExpandedState, RowSelectionState, SortingState, TableOptions } from '@tanstack/react-table';
 export { createColumnHelper } from '@tanstack/react-table';
 import { PopoverProps as PopoverProps$1, ToggleButtonProps, ToggleButtonGroupProps, ListBoxProps as ListBoxProps$1, ListBoxItemProps as ListBoxItemProps$1, ListBoxSectionProps as ListBoxSectionProps$1, HeaderProps, ComboBoxProps as ComboBoxProps$1, ValidationResult, TextFieldProps as TextFieldProps$1 } from 'react-aria-components';
@@ -161,6 +161,32 @@ type IconButtonProps = (Omit<InternalButtonProps, 'fullWidth' | 'children'> | Om
 declare const IconButton: ({ "aria-label": ariaLabel, className, ...props }: IconButtonProps) => React$1.JSX.Element;
 //# sourceMappingURL=IconButton.d.ts.map
 
+type Alignment = 'start' | 'end';
+type Side = 'top' | 'right' | 'bottom' | 'left';
+type AlignedPlacement = `${Side}-${Alignment}`;
+type Placement = Side | AlignedPlacement;
+type Interactions = 'click' | 'hover' | 'focus' | 'dismiss';
+type OverlayAriaRole = 'tooltip' | 'dialog' | 'alertdialog' | 'menu' | 'listbox' | 'grid' | 'tree';
+
+type CopyToClipboardSize = 'sm' | 'md' | 'lg';
+type CopyToClipboardVariant = 'primary' | 'secondary' | 'tertiary' | 'ghost';
+type CopyToClipboardProps = {
+    value: string;
+    copyLabel?: string;
+    copiedLabel?: string;
+    copyErrorLabel?: string;
+    size?: CopyToClipboardSize;
+    variant?: CopyToClipboardVariant;
+    disabled?: boolean;
+    resetAfterMs?: number;
+    tooltipPlacement?: Placement;
+    onCopy?: (value: string) => void;
+    onCopyError?: (error: unknown) => void;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onCopy' | 'children' | 'value' | 'type'>;
+
+declare const CopyToClipboard: ({ value, copyLabel, copiedLabel, copyErrorLabel, size, variant, disabled, resetAfterMs, tooltipPlacement, onCopy, onCopyError, onClick, className, ...rest }: CopyToClipboardProps) => React$1.JSX.Element;
+//# sourceMappingURL=CopyToClipboard.d.ts.map
+
 type TableSize = 'sm' | 'md' | 'lg';
 type ColumnAlign = 'left' | 'right';
 type RowReorderMode = 'siblings' | 'same-level' | 'all';
@@ -281,13 +307,6 @@ type LoadingSpinnerProps = {
 declare const LoadingSpinner: ({ size, white, className, }: LoadingSpinnerProps) => React$1.JSX.Element;
 //# sourceMappingURL=LoadingSpinner.d.ts.map
 
-type Alignment = 'start' | 'end';
-type Side = 'top' | 'right' | 'bottom' | 'left';
-type AlignedPlacement = `${Side}-${Alignment}`;
-type Placement = Side | AlignedPlacement;
-type Interactions = 'click' | 'hover' | 'focus' | 'dismiss';
-type OverlayAriaRole = 'tooltip' | 'dialog' | 'alertdialog' | 'menu' | 'listbox' | 'grid' | 'tree';
-
 type OverlayTriggerSettings = {
     placement?: Placement;
     isInitiallyActive?: boolean;
@@ -932,5 +951,5 @@ type AuthLayoutProps = {
 declare const AuthLayout: ({ children, heading, description, sentiment, leadingElement, alert, topAddon, footer, }: AuthLayoutProps) => React$1.JSX.Element;
 //# sourceMappingURL=AuthLayout.d.ts.map
 
-export { ActionList, Alert, AuthLayout, Avatar, Banner, Body, Breadcrumbs, BreadcrumbsItem, Button, Card, Checkbox, CheckboxGroup, Chip, Code, ComboBox, DataTable, Display, Drawer, EmptyState, Flex, FormErrorMessage, FormHelperText, GlobalToastProvider, Grid, Heading, Icon, IconButton, Label, Link, ListBox, LoadingSpinner, Logo, Menu, MenuButton, MenuList, OverlayTrigger, Pagination, Popover, ProgressBar, Radio, RadioGroup, SegmentedControl, Select, SideNavWrapper as SideNav, Tab, TabList, TabPanel, TabPanels, Tabs, Tag, TextArea, TextField, TextInput, Tile, ToastProvider, ToastQueue, Toggle, Tooltip, TooltipTrigger, TopBar, useElementResizeObserver, useHover, useOverlayTrigger, useToast, useWindowSize };
-export type { ComboBoxProps, DrawerProps, EmptyStateHeadingLevel, EmptyStateProps, Interactions, OverlayAriaRole, Placement, PopoverProps, SegmentedControlItemProps, SegmentedControlProps, SegmentedControlSize, TextAreaProps, TextFieldProps, TextInputProps };
+export { ActionList, Alert, AuthLayout, Avatar, Banner, Body, Breadcrumbs, BreadcrumbsItem, Button, Card, Checkbox, CheckboxGroup, Chip, Code, ComboBox, CopyToClipboard, DataTable, Display, Drawer, EmptyState, Flex, FormErrorMessage, FormHelperText, GlobalToastProvider, Grid, Heading, Icon, IconButton, Label, Link, ListBox, LoadingSpinner, Logo, Menu, MenuButton, MenuList, OverlayTrigger, Pagination, Popover, ProgressBar, Radio, RadioGroup, SegmentedControl, Select, SideNavWrapper as SideNav, Tab, TabList, TabPanel, TabPanels, Tabs, Tag, TextArea, TextField, TextInput, Tile, ToastProvider, ToastQueue, Toggle, Tooltip, TooltipTrigger, TopBar, useElementResizeObserver, useHover, useOverlayTrigger, useToast, useWindowSize };
+export type { ComboBoxProps, CopyToClipboardProps, CopyToClipboardSize, CopyToClipboardVariant, DrawerProps, EmptyStateHeadingLevel, EmptyStateProps, Interactions, OverlayAriaRole, Placement, PopoverProps, SegmentedControlItemProps, SegmentedControlProps, SegmentedControlSize, TextAreaProps, TextFieldProps, TextInputProps };