@ahrowe/ui 0.12.0 → 0.13.0

package/docs/Alert.md

@@ -0,0 +1,64 @@
+# Alert
+
+**When to use:** A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices. Unlike `Toast`, it isn't portaled or auto-dismissed, and it stays in the page's normal flow for as long as its consumer renders it. Use `Toast` instead for a transient, corner-anchored notification.
+
+**Import:** `import { Alert, AlertStyleType } from '@ahrowe/ui'`
+
+**Style variants:** `AlertStyleType.Default` | `AlertStyleType.Info` | `AlertStyleType.Success` | `AlertStyleType.Warn` | `AlertStyleType.Error`
+
+```tsx
+import { Alert, AlertStyleType } from '@ahrowe/ui';
+
+// Default, neutral message
+<Alert>A default, neutral message.</Alert>
+
+// Semantic variants
+<Alert styleType={AlertStyleType.Info}>Here's something worth knowing.</Alert>
+<Alert styleType={AlertStyleType.Success}>Your changes were saved.</Alert>
+<Alert styleType={AlertStyleType.Warn}>Your storage is almost full.</Alert>
+<Alert styleType={AlertStyleType.Error}>Something went wrong. Please try again.</Alert>
+
+// With a title
+<Alert styleType={AlertStyleType.Warn} title="Storage almost full">
+  You've used 92% of your available space. Free up room or upgrade your plan.
+</Alert>
+
+// Dismissible: the consumer owns visibility. onClose is called on click,
+// so stop rendering the Alert (or flip your own state) to actually hide it
+const [visible, setVisible] = useState(true);
+{visible && (
+  <Alert
+    styleType={AlertStyleType.Info}
+    title="New feature available"
+    onClose={() => setVisible(false)}
+  >
+    Try out the new dashboard layout from your account settings.
+  </Alert>
+)}
+
+// Without the leading icon
+<Alert styleType={AlertStyleType.Success} hideIcon>
+  A minimal message with no leading icon.
+</Alert>
+
+// Custom icon, overriding the styleType default
+import { faRocket } from '@fortawesome/free-solid-svg-icons';
+<Alert styleType={AlertStyleType.Info} icon={faRocket}>
+  Shipping a new release tonight.
+</Alert>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `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` |
+| `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 |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Alert: { hideIcon: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `icon` `content` `title` `description` `closeButton`

package/docs/Breadcrumb.md

@@ -0,0 +1,106 @@
+# Breadcrumb
+
+**When to use:** A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page. The last item is always rendered as the current page and isn't clickable.
+
+**Import:** `import { Breadcrumb } from '@ahrowe/ui'`
+**Types:** `import type { BreadcrumbItem, BreadcrumbProps } from '@ahrowe/ui'`
+
+```tsx
+import { Breadcrumb } from '@ahrowe/ui';
+import type { BreadcrumbItem } from '@ahrowe/ui';
+
+const items: BreadcrumbItem[] = [
+  { label: 'Home', href: '/' },
+  { label: 'Documents', href: '/documents' },
+  { label: 'Report.pdf' }, // last item: rendered as the current page, not a link
+];
+
+<Breadcrumb items={items} />
+
+// With leading icons
+import { faHouse, faFolder } from '@fortawesome/free-solid-svg-icons';
+
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/', icon: faHouse },
+    { label: 'Projects', href: '/projects', icon: faFolder },
+    { label: 'Current project' },
+  ]}
+/>
+
+// Client-side routing (e.g. react-router): keep href for a real, right-clickable link,
+// and use onClick to intercept the native navigation with the router's own navigate()
+import { useNavigate } from 'react-router-dom';
+
+function Example() {
+  const navigate = useNavigate();
+  return (
+    <Breadcrumb
+      items={[
+        {
+          label: 'Home',
+          href: '/',
+          onClick: (event) => {
+            event.preventDefault();
+            navigate('/');
+          },
+        },
+        { label: 'Current page' },
+      ]}
+    />
+  );
+}
+
+// A disabled crumb: dimmed, not clickable, regardless of href/onClick
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Archived', href: '/archived', disabled: true },
+    { label: 'Old report' },
+  ]}
+/>
+
+// Custom separator (default is a chevron icon)
+<Breadcrumb items={items} separator="/" />
+
+// Long trails: collapse the middle behind a clickable ellipsis once items.length
+// exceeds maxItems. The ellipsis counts as one of the visible slots, so maxItems={3}
+// on a 4-item trail shows: Home / ... / Settings. Clicking the ellipsis opens a menu
+// (via FloatingMenu) listing the hidden items.
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Invoices', href: '/invoices' },
+    { label: 'Editor', href: '/invoices/editor' },
+    { label: 'Settings' },
+  ]}
+  maxItems={3}
+/>
+```
+
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `maxItems` is used and the trail actually collapses (the hidden-items menu is a `FloatingMenu`, which renders via portal).
+
+**BreadcrumbItem:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `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 |
+| `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` |
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `BreadcrumbItem[]` | The crumbs, in order. The last one is always rendered as the current page |
+| `separator` | `ReactNode` | Overrides the default chevron separator between items |
+| `maxItems` | `number` | Collapses the middle items behind a clickable ellipsis once `items.length` exceeds this. The ellipsis counts as one of the visible slots, alongside the always-shown first item (so `maxItems={3}` shows first item, ellipsis, last item) |
+
+**Collapsing behaviour:** the hidden count grows and shrinks by exactly however many items are actually over the limit, rather than always jumping to the same minimal first/ellipsis/last shape. A trail with 11 items and `maxItems={10}` hides only 2 items, not the whole middle, so the trail doesn't visually lurch as one more level of navigation pushes it just over the limit.
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Breadcrumb: { separator: '/' } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `list` `item` `link` `icon` `separator` `current` `ellipsis` `hiddenList` `hiddenItem`

package/docs/CLAUDE.md

@@ -95,13 +95,16 @@ Slot keys per component are documented in each component's doc file below.
 @Accordion.md
 @ActionButtons.md
 @ActionIcon.md
+@Alert.md
 @AnimatedLogo.md
 @AnimatedText.md
 @Avatar.md
 @Badge.md
 @BodyEnd.md
+@Breadcrumb.md
 @Button.md
 @Card.md
+@Carousel.md
 @Checkbox.md
 @Chip.md
 @ColorPicker.md
@@ -133,6 +136,7 @@ Slot keys per component are documented in each component's doc file below.
 @Popover.md
 @ProgressBar.md
 @RadioGroup.md
+@Rating.md
 @Ripple.md
 @RoomDrawer.md
 @RoomViewer.md

package/docs/Carousel.md

@@ -0,0 +1,67 @@
+# Carousel
+
+**When to use:** A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay. Slides are plain children, so any content works (images, cards, mixed content), not just a fixed image-gallery shape.
+
+**Import:** `import { Carousel } from '@ahrowe/ui'`
+**Types:** `import type { CarouselProps } from '@ahrowe/ui'`
+
+```tsx
+import { Carousel } from '@ahrowe/ui';
+
+// Uncontrolled, looping by default, with arrows, dots, and swipe all on
+<Carousel>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</Carousel>
+
+// Controlled
+const [index, setIndex] = useState(0);
+<Carousel currentIndex={index} onChange={setIndex}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</Carousel>
+
+// Autoplay, paused on hover/focus by default, with dots hidden
+<Carousel autoPlay autoPlayInterval={4000} showDots={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+
+// Bounded instead of looping: arrows disable at the first/last slide
+<Carousel loop={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+
+// No swipe/drag, arrows only
+<Carousel swipeable={false} showDots={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+```
+
+Pass slides as direct children (an array or a set of sibling elements), not through a component that returns a fragment internally. `Carousel` reads its immediate children via `React.Children`, so a wrapper component's own children aren't visible to it. If slides come from a `.map()`, spread the array straight into `Carousel`, the same way `children` normally works in React.
+
+**Interaction:** drag or swipe the track to move between slides (committing past roughly 20% of the container's width, or releasing further than that snaps to the next/previous slide; a shorter drag springs back). Left/right arrow keys move between slides when focus is anywhere inside the carousel.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The slides, one per direct child |
+| `currentIndex` | `number` | Controlled active slide index |
+| `defaultIndex` | `number` | Initial active slide index when uncontrolled (default `0`) |
+| `onChange` | `(index: number) => void` | Called whenever the active slide changes, from arrows, dots, keyboard, drag, or autoplay |
+| `loop` | `boolean` | Wrap from the last slide to the first and back (default `true`) |
+| `autoPlay` | `boolean` | Automatically advance on a timer (default `false`) |
+| `autoPlayInterval` | `number` | Autoplay delay in ms (default `4000`) |
+| `pauseOnHover` | `boolean` | Pause autoplay while hovered or focused (default `true`) |
+| `showArrows` | `boolean` | Show the prev/next buttons (default `true`); hidden automatically with one slide or none |
+| `showDots` | `boolean` | Show the position dots (default `true`); hidden automatically with one slide or none |
+| `swipeable` | `boolean` | Allow dragging/swiping the track (default `true`) |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Carousel: { autoPlay: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `track` `slide` `prevButton` `nextButton` `dots` `dot`

package/docs/Rating.md

@@ -0,0 +1,72 @@
+# Rating
+
+**When to use:** A star rating input or display, for review scores, feedback prompts, and quality indicators. Use `readOnly` to just show an existing rating (e.g. a product's average score) rather than collect one.
+
+**Import:** `import { Rating } from '@ahrowe/ui'`
+**Types:** `import type { RatingProps } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Rating } from '@ahrowe/ui';
+
+// Controlled
+const [value, setValue] = useState(3);
+<Rating value={value} onChange={setValue} />
+
+// Uncontrolled
+<Rating defaultValue={4} onChange={(value) => console.log(value)} />
+
+// Half-star increments
+<Rating defaultValue={3.5} allowHalf />
+
+// A different number of stars
+<Rating defaultValue={6} max={10} />
+
+// Read-only, for displaying an existing rating (e.g. a product card)
+<Rating value={4} readOnly />
+
+// Disabled
+<Rating value={2} disabled />
+
+// Larger, via font-size (sizing is em-based, like Switch and Avatar)
+<Rating defaultValue={4} style={{ fontSize: 32 }} />
+
+// Custom icon
+import { faHeart } from '@fortawesome/free-solid-svg-icons';
+<Rating defaultValue={3} icon={faHeart} />
+
+// Disable click-to-clear (clicking the currently-selected star normally resets to 0)
+<Rating value={value} onChange={setValue} allowClear={false} />
+```
+
+**Interaction:** click, tap, or drag/swipe across the stars to set the rating, on any pointer type (mouse, touch, pen) via the Pointer Events API. Dragging updates the preview live and commits on release, which is the natural gesture on mobile rather than requiring a precise tap on one star. A plain click/tap on the currently-selected star clears it to `0` (set `allowClear={false}` to keep it fixed instead); a drag that happens to end back near its starting value doesn't clear, since that's a different gesture from a deliberate re-tap. With keyboard focus: `←`/`↓` and `→`/`↑` move by one star (or half a star with `allowHalf`), `Home`/`End` jump to `0`/`max`.
+
+**Sizing:** there's no dedicated size prop, `font-size` scales the whole control (like `Switch` and `Avatar`). The root sizes to its content (`width: fit-content`) rather than stretching to fill a flex/grid ancestor, since the click/drag position is measured against the root's own width.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `number` | Controlled value (omit for uncontrolled) |
+| `defaultValue` | `number` | Initial value when uncontrolled (default `0`) |
+| `onChange` | `(value: number) => void` | Fires when the rating changes, from a click or keyboard input |
+| `max` | `number` | Number of stars (default `5`) |
+| `allowHalf` | `boolean` | Allow half-star increments (default `false`) |
+| `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 |
+| `aria-label` | `string` | Accessible label (default `'Rating'`) |
+
+**Accessibility:** renders `role="slider"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`/`aria-valuetext`, matching `Slider`'s pattern.
+
+**Theming:** override these CSS variables theme-wide via `ThemeProvider` or per instance via `style`; each falls back to a built-in default:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--rating-filled-color` | `var(--primary-color)` |
+| `--rating-empty-color` | `var(--background-accent-light)` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Rating: { allowHalf: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `item` `iconEmpty` `iconFilled`

package/package.json

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