@ahrowe/ui 0.20.0 → 0.22.0

package/dist/types/package/common/breadcrumb/breadcrumb.types.d.ts

@@ -1,11 +1,11 @@
 import { CSSProperties, MouseEvent, ReactNode } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export interface BreadcrumbItem {
     id?: string;
     label: ReactNode;
     href?: string;
-    icon?: IconDefinition;
+    icon?: IconContent;
     onClick?: (event: MouseEvent) => void;
     disabled?: boolean;
 }

package/dist/types/package/common/button/button.types.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties } from 'react';
-import { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export declare enum ButtonStyleType {
     Primary = "primary",
@@ -26,7 +26,7 @@ export interface ButtonProps extends HtmlProps {
     size?: ButtonSize;
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void> | void;
     children?: React.ReactNode;
-    icon?: IconDefinition;
+    icon?: IconContent;
     isLoading?: boolean;
     disabled?: boolean;
     title?: string;

package/dist/types/package/common/emptyState/emptyState.types.d.ts

@@ -1,8 +1,8 @@
 import { ReactNode } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { HtmlProps } from '../types/slots.types';
 export interface EmptyStateProps extends HtmlProps {
     className?: string;
-    icon?: IconDefinition;
+    icon?: IconContent;
     children?: ReactNode;
 }

package/dist/types/package/common/fab/fab.types.d.ts

@@ -1,10 +1,10 @@
 import { ReactNode } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { HtmlProps } from '../types/slots.types';
 export type FabSize = 'default' | 'mini';
 export interface FabMenuEntry {
     id: string;
-    icon: IconDefinition;
+    icon: IconContent;
     label?: string;
 }
 export interface FabProps extends HtmlProps {

package/dist/types/package/common/rating/rating.types.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type RatingSlots = 'root' | 'item' | 'iconEmpty' | 'iconFilled';
 export interface RatingProps extends HtmlProps {
@@ -11,7 +11,7 @@ export interface RatingProps extends HtmlProps {
     allowClear?: boolean;
     readOnly?: boolean;
     disabled?: boolean;
-    icon?: IconDefinition;
+    icon?: IconContent;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<RatingSlots>;

package/dist/types/package/common/sectionHeader/sectionHeader.types.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactNode } from 'react';
-import { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 import { IconAction } from '../types/actions.types';
 export declare enum SectionHeaderSize {
@@ -8,11 +8,11 @@ export declare enum SectionHeaderSize {
     Large = "large"
 }
 export type SectionHeaderAction = IconAction;
-export type SectionHeaderSlots = 'root' | 'leading' | 'titles' | 'title' | 'subtitle' | 'trailing' | 'left' | 'center' | 'actions';
+export type SectionHeaderSlots = 'root' | 'identity' | 'leading' | 'titles' | 'title' | 'subtitle' | 'trailing' | 'left' | 'center' | 'actions';
 export interface SectionHeaderProps extends HtmlProps {
     title?: ReactNode;
     subtitle?: ReactNode;
-    icon?: IconDefinition;
+    icon?: IconContent;
     thumbnail?: string | ReactNode;
     left?: ReactNode;
     center?: ReactNode;

package/dist/types/package/common/splitButton/splitButton.types.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactNode } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { ButtonStyleType, ButtonSize } from '../button/button.types';
 import { Align } from '../floatingMenu/floatingMenu.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
@@ -8,7 +8,7 @@ export interface SplitButtonAction {
     label: ReactNode;
     onClick: () => void;
     disabled?: boolean;
-    icon?: IconDefinition;
+    icon?: IconContent;
 }
 export type SplitButtonSlots = 'root' | 'primaryButton' | 'triggerButton' | 'menu' | 'menuItem';
 export interface SplitButtonProps extends HtmlProps {

package/dist/types/package/common/stepper/stepper.types.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 /** Layout direction of the stepper. */
 export declare enum StepperAlignment {
@@ -46,8 +46,8 @@ export interface StepperStep {
     description?: React.ReactNode;
     /** Collapsible body content, rendered under the label (vertical only). */
     content?: React.ReactNode;
-    /** FontAwesome icon shown in the marker instead of the step number. */
-    icon?: IconDefinition;
+    /** Icon shown in the marker instead of the step number — a FontAwesome icon or any node. */
+    icon?: IconContent;
     /** Marks the step as errored, recolouring the marker with `--stepper-error-color`. */
     error?: boolean;
     /** `true` renders an "Optional" hint; a node renders custom hint text. */

package/dist/types/package/common/tabHeader/tabHeader.types.d.ts

@@ -1,10 +1,10 @@
 import { default as React } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type TabHeaderSlots = 'root' | 'tab' | 'icon' | 'labels' | 'title' | 'subtitle';
 export interface TabHeaderTab {
     id: string;
-    icon: IconDefinition;
+    icon: IconContent;
     title?: string;
     subtitle?: string;
     disabled?: boolean;

package/dist/types/package/common/timeline/timeline.types.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 /** Layout of entries relative to the connecting line. */
 export declare enum TimelineAlignment {
@@ -28,8 +28,8 @@ export interface TimelineItem {
     description?: React.ReactNode;
     /** Rendered next to the title, e.g. a date or relative time ("2 hours ago"). */
     timestamp?: React.ReactNode;
-    /** FontAwesome icon shown in the marker instead of a plain dot. */
-    icon?: IconDefinition;
+    /** Icon shown in the marker instead of a plain dot — a FontAwesome icon or any node. */
+    icon?: IconContent;
     /** Semantic marker colour (default `Default`). */
     status?: TimelineItemStatus;
     /** Extra content rendered under the description, e.g. a diff, an attachment, an actor avatar. */

package/dist/types/package/common/types/actions.types.d.ts

@@ -1,7 +1,7 @@
-import { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+import { IconContent } from './icon.types';
 /** A single icon-triggered action, rendered as an `ActionIcon` */
 export interface IconAction {
     title?: string;
     onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
-    icon: IconDefinition;
+    icon: IconContent;
 }

package/dist/types/package/common/types/icon.types.d.ts

@@ -0,0 +1,17 @@
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { ReactElement } from 'react';
+/**
+ * Anything a component will accept for an `icon` prop: either a FontAwesome
+ * `IconDefinition` (rendered through `FontAwesomeIcon`) or an arbitrary React
+ * element (rendered as-is) — an `<img>`, an inline `<svg>`, another icon
+ * library's component, …
+ *
+ * Deliberately `ReactElement` rather than `ReactNode`: `ReactNode` also covers
+ * strings, numbers and booleans, so a required icon prop would stop catching
+ * `icon="star"` at compile time and silently render the text instead. Matches
+ * what `Input` has always accepted for its own icon prop.
+ *
+ * Render one with `renderIcon` from `components/common/utils/renderIcon`, which
+ * picks the right branch.
+ */
+export type IconContent = IconDefinition | ReactElement;

package/dist/types/package/common/utils/renderIcon.d.ts

@@ -0,0 +1,29 @@
+import { CSSProperties, ReactNode } from 'react';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { IconContent } from '../types/icon.types';
+interface RenderIconOptions {
+    /** Class applied to the rendered icon (or to the wrapper span for a custom element). */
+    className?: string;
+    /** Inline style applied to the rendered icon (or to the wrapper span for a custom element). */
+    style?: CSSProperties;
+}
+/**
+ * Narrows an `IconContent` to a FontAwesome `IconDefinition`.
+ *
+ * Both halves of the union are plain objects (a React element is one too), so
+ * they can only be told apart structurally: an icon definition always carries
+ * `prefix`, `iconName` and the `icon` tuple.
+ */
+export declare function isIconDefinition(icon: IconContent | null | undefined): icon is IconDefinition;
+/**
+ * Renders an `icon` prop that may be either a FontAwesome `IconDefinition` or an
+ * arbitrary React element.
+ *
+ * A definition goes through `FontAwesomeIcon`; an element is returned untouched
+ * unless a `className`/`style` was given, in which case it is wrapped in a
+ * `<span>` carrying them so component and consumer slot styling still lands
+ * somewhere. Note that a custom element is not sized by FontAwesome's `1em`
+ * geometry — size it yourself if the surrounding layout expects a square icon.
+ */
+export declare function renderIcon(icon: IconContent | null | undefined, options?: RenderIconOptions): ReactNode;
+export {};

package/docs/ActionIcon.md

@@ -23,7 +23,7 @@ import { faTrash } from '@fortawesome/free-solid-svg-icons';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `icon` | `IconDefinition` | FontAwesome icon (required) |
+| `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element (required) |
 | `title` | `string` | Tooltip / accessible label |
 | `onClick` | `(event: MouseEvent) => void` | Click handler |
 | `className` | `string` | Root element class |

package/docs/Alert.md

@@ -57,7 +57,7 @@ import { faRocket } from '@fortawesome/free-solid-svg-icons';
 | `title` | `ReactNode` | Optional bold heading above the description |
 | `children` | `ReactNode` | The message body |
 | `styleType` | `AlertStyleType` | Colour variant and default icon (default `Default`) |
-| `icon` | `IconDefinition` | Overrides the default FontAwesome icon for `styleType` |
+| `icon` | `IconDefinition \| ReactElement` | Overrides the default icon for `styleType` — FontAwesome icon or any React element |
 | `hideIcon` | `boolean` | Hide the leading icon entirely |
 | `onClose` | `() => void` | Shows a close button and is called when it's clicked. `Alert` doesn't hide itself, so stop rendering it (or update your own state) in the handler |
 

package/docs/Avatar.md

@@ -46,7 +46,7 @@ import { Avatar, AvatarGroup } from '@ahrowe/ui';
 | `src` | `string` | Image URL |
 | `alt` | `string` | Image alt text (falls back to `name`) |
 | `name` | `string` | Used to derive fallback initials, and as `alt` text when `alt` isn't given |
-| `icon` | `IconDefinition` | FontAwesome icon shown when there's no `src` and no `name` (default a person icon) |
+| `icon` | `IconDefinition \| ReactElement` | Icon shown when there's no `src` and no `name` — FontAwesome icon or any React element (default a person icon) |
 | `content` | `ReactNode` | Custom fallback content overriding the computed initials/icon (e.g. `"+3"` — what `AvatarGroup` uses for its overflow indicator) |
 | `status` | `'online' \| 'away' \| 'busy' \| 'offline'` | Small status dot on the bottom-right corner, rendered via `Badge` |
 | `className` / `style` | | Root element — sizing is `em`-based, so `style={{ fontSize }}` scales the whole avatar. Shape defaults to `var(--default-border-radius)`; override via the `--avatar-radius` custom property (e.g. `'50%'` for fully circular) |

package/docs/Breadcrumb.md

@@ -89,7 +89,7 @@ function Example() {
 | `id` | `string` | Optional stable key; falls back to the item's index |
 | `label` | `ReactNode` | The crumb's text |
 | `href` | `string` | Renders the crumb as a real `<a>`. Omit to render a plain clickable element (with `onClick`) or static text |
-| `icon` | `IconDefinition` | Optional leading FontAwesome icon |
+| `icon` | `IconDefinition \| ReactElement` | Optional leading icon — FontAwesome icon or any React element |
 | `onClick` | `(event: MouseEvent) => void` | Click handler. Works alongside `href`: call `event.preventDefault()` to stop the native navigation and hand off to a client-side router's own navigate function (see the react-router example above). Also works on its own, with no `href` |
 | `disabled` | `boolean` | Dims the crumb and makes it non-interactive, regardless of `href`/`onClick` |
 

package/docs/Button.md

@@ -46,7 +46,7 @@ import { faSave } from '@fortawesome/free-solid-svg-icons';
 | `styleType` | `ButtonStyleType` | Visual variant |
 | `size` | `ButtonSize` | Size variant |
 | `type` | `ButtonType` | HTML button type |
-| `icon` | `IconDefinition` | FontAwesome icon shown before label |
+| `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
 | `isLoading` | `boolean` | Replaces content with a spinner |
 | `disabled` | `boolean` | |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |

package/docs/CLAUDE.md

@@ -90,6 +90,28 @@ Most components expose `classNames` and `styles` props for styling inner element
 
 Slot keys per component are documented in each component's doc file below.
 
+## Icon props (`IconDefinition | ReactElement`)
+
+Every `icon` prop (and every icon field inside an item/action object) accepts either a
+FontAwesome `IconDefinition` or an arbitrary React node — an inline `<svg>`, an `<img>`,
+or another icon library's component.
+
+```tsx
+import { faPen } from '@fortawesome/free-solid-svg-icons';
+
+<Button icon={faPen}>Edit</Button>                    // FontAwesome
+<Button icon={<MyIcon />}>Edit</Button>               // any React node
+<Button icon={<img src="/pen.svg" alt="" />}>Edit</Button>
+```
+
+A definition is rendered through `FontAwesomeIcon`; an element is rendered as-is, wrapped in a
+`<span>` carrying the component's icon class when that slot is styled. A custom element is not
+sized by FontAwesome's `1em` geometry, so give it its own width/height if the surrounding
+layout expects a square icon.
+
+`IconPicker` and the internal `AnimatedIcon` are the exceptions — their behaviour depends on
+FontAwesome internals, so they still take an `IconDefinition` only.
+
 ## Component docs
 
 @Accordion.md

package/docs/EmptyState.md

@@ -25,6 +25,6 @@ import { faInbox } from '@fortawesome/free-solid-svg-icons';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `icon` | `IconDefinition` | FontAwesome icon shown above the message |
+| `icon` | `IconDefinition \| ReactElement` | Icon shown above the message — FontAwesome icon or any React element |
 | `children` | `ReactNode` | Message body (defaults to `"No entries available"`) |
 | `className` | `string` | Root element class |

package/docs/Rating.md

@@ -55,7 +55,7 @@ import { faHeart } from '@fortawesome/free-solid-svg-icons';
 | `allowClear` | `boolean` | Clicking the currently-selected star resets the value to `0` (default `true`) |
 | `readOnly` | `boolean` | Display only, not focusable or interactive |
 | `disabled` | `boolean` | Dims the control and disables interaction |
-| `icon` | `IconDefinition` | Overrides the default star icon |
+| `icon` | `IconDefinition \| ReactElement` | Overrides the default star icon — FontAwesome icon or any React element |
 | `aria-label` | `string` | Accessible label (default `'Rating'`) |
 
 **Accessibility:** renders `role="slider"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`/`aria-valuetext`, matching `Slider`'s pattern.

package/docs/SectionHeader.md

@@ -62,7 +62,7 @@ import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';
 |------|------|-------------|
 | `title` | `ReactNode` | Main heading |
 | `subtitle` | `ReactNode` | Secondary text below the title |
-| `icon` | `IconDefinition` | FontAwesome icon shown on the left; ignored when `thumbnail` is set |
+| `icon` | `IconDefinition \| ReactElement` | Icon shown on the left (FontAwesome icon or any React element); ignored when `thumbnail` is set |
 | `thumbnail` | `string \| ReactNode` | URL → background image; any other ReactNode → rendered inside the leading circle |
 | `left` | `ReactNode` | Leftmost content of the trailing block (title stays fixed to the left of it) |
 | `center` | `ReactNode` | Center content of the trailing block, e.g. a search box or tabs |
@@ -76,7 +76,7 @@ import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';
 ```ts
 interface SectionHeaderAction {
   title?: string;
-  icon: IconDefinition;
+  icon: IconDefinition | ReactElement;
   onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
 }
 ```
@@ -85,8 +85,8 @@ interface SectionHeaderAction {
 
 **Theming:** title size/weight per `size` variant come from the theme, with local fallbacks — `SectionHeaderSize.Large` uses `--header-font-size` (falls back `24px`), `Medium` uses `--header-medium-font-size` (falls back `18px`), `Small` uses `--header-small-font-size` (falls back `16px`); all three use `--header-font-weight` for the title's font weight (falls back `600`). The leading icon/thumbnail is sized at `2.2×` the title size, so it scales automatically with the theme; the subtitle size is fixed per `size` variant (not derived), since it doesn't track the title proportionally at the `Large` size. See [ThemeProvider.md](ThemeProvider.md).
 
-**Layout:** the title (with its leading icon/thumbnail) is fixed to the left and only takes the width its content needs. Everything after it — `left`, `center`, `actions` — lives in a separate `trailing` flex block laid out with `space-between`, so `center` is centered within that block (not the whole header) regardless of how wide `left`/`actions` are.
+**Layout:** the title and its leading icon/thumbnail sit together in an `identity` wrapper that is fixed to the left and only takes the width its content needs; they never wrap apart from each other. The title itself renders on a single line and truncates with an ellipsis (a plain-string `title` is also set as the element's `title` attribute, so the full text is available on hover); the subtitle is clamped to two lines. Everything after it — `left`, `center`, `actions` — lives in a separate `trailing` flex block laid out with `space-between`, so `center` is centered within that block (not the whole header) regardless of how wide `left`/`actions` are.
 
-**Responsive:** the header wraps — if `trailing` (`left`/`center`/`actions`) doesn't fit next to the title, it drops to its own row; if `trailing` itself doesn't fit as one row, its own children wrap too. Below `640px` viewport width, `center` additionally takes a full-width row of its own, so a wide `center` element (e.g. a `SearchInput`) isn't squeezed alongside `left`/`actions` on small screens.
+**Responsive:** the header wraps — if `trailing` (`left`/`center`/`actions`) doesn't fit next to the `identity` block, it drops to its own row; if `trailing` itself doesn't fit as one row, its own children wrap too. Below `640px` viewport width, `center` additionally takes a full-width row of its own, so a wide `center` element (e.g. a `SearchInput`) isn't squeezed alongside `left`/`actions` on small screens.
 
-**Slots:** `root` `leading` `titles` `title` `subtitle` `trailing` `left` `center` `actions`
+**Slots:** `root` `identity` `leading` `titles` `title` `subtitle` `trailing` `left` `center` `actions`

package/docs/Stepper.md

@@ -69,7 +69,7 @@ const steps = [
 | `label` | `ReactNode` | Primary step label |
 | `description` | `ReactNode` | Secondary line under the label |
 | `content` | `ReactNode` | Collapsible body under the label (vertical only) |
-| `icon` | `IconDefinition` | FontAwesome icon in the marker, replacing the number |
+| `icon` | `IconDefinition \| ReactElement` | Icon in the marker, replacing the number — FontAwesome icon or any React element |
 | `error` | `boolean` | Recolours the marker with `--stepper-error-color`; suppresses the checkmark |
 | `optional` | `boolean \| ReactNode` | `true` → an "Optional" hint; a node → custom hint text |
 | `disabled` | `boolean` | Never clickable, dimmed |

package/docs/TabHeader.md

@@ -56,7 +56,7 @@ function Example() {
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `string` | Unique identifier, matched against `currentTab` |
-| `icon` | `IconDefinition` | FontAwesome icon (always visible, incl. mobile) |
+| `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element (always visible, incl. mobile) |
 | `title` | `string` | Optional title next to the icon |
 | `subtitle` | `string` | Optional subtitle beneath the title |
 | `disabled` | `boolean` | Dim the tab and prevent selection |

package/docs/Timeline.md

@@ -87,7 +87,7 @@ function AuditLog() {
 | `title` | `ReactNode` | Primary label for the entry |
 | `description` | `ReactNode` | Secondary line under the title |
 | `timestamp` | `ReactNode` | Rendered next to the title, e.g. a date or relative time ("2 hours ago") |
-| `icon` | `IconDefinition` | FontAwesome icon shown in the marker instead of a plain dot |
+| `icon` | `IconDefinition \| ReactElement` | Icon shown in the marker instead of a plain dot — FontAwesome icon or any React element |
 | `status` | `TimelineItemStatus` | Semantic marker colour (default `Default`) |
 | `content` | `ReactNode` | Extra content rendered under the description, e.g. a diff, an attachment, an actor avatar |
 | `onClick` | `(event: MouseEvent<HTMLDivElement>) => void` | Makes the whole entry clickable, rendering it as an accessible button (`role="button"`, focusable, click and Enter both fire it). Omit to render a plain, non-interactive row |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "publishConfig": {
     "access": "public"
   },