@ahrowe/ui 0.2.9 → 0.3.0

package/docs/Avatar.md

@@ -0,0 +1,62 @@
+# Avatar
+
+**When to use:** User or entity image — profile pictures, comment authors, member lists. Falls back to initials (derived from `name`) or an icon when there's no image, or the image fails to load. Use `AvatarGroup` to stack several with overlap and a `+N` overflow indicator.
+
+**Import:** `import { Avatar, AvatarGroup } from '@ahrowe/ui'`
+
+**Theming:** shape defaults to `var(--default-border-radius)`. Set `--avatar-radius` (per `Avatar`/`AvatarGroup` via `style`, or theme-wide via `ThemeProvider`'s `variables`) to override it — `'50%'` for fully circular avatars is the most common case. See [ThemeProvider.md](ThemeProvider.md).
+
+```tsx
+import { Avatar, AvatarGroup } from '@ahrowe/ui';
+
+// Image, with initials/icon fallback if it 404s
+<Avatar src="https://example.com/avatar.jpg" name="Jane Doe" />
+
+// No image — shows initials
+<Avatar name="Jane Doe" />
+
+// No image, no name — shows a default person icon (or pass a custom `icon`)
+<Avatar />
+
+// Status dot
+<Avatar name="Jane Doe" status="online" />
+
+// Resize — sizing is `em`-based, so font-size scales the whole avatar
+<Avatar name="Jane Doe" style={{ fontSize: '32px' }} />
+
+// Fully circular instead of the default --default-border-radius — set on one Avatar,
+// or on an AvatarGroup to cascade to every avatar inside (and its separator ring)
+<Avatar name="Jane Doe" style={{ '--avatar-radius': '50%' }} />
+
+// Group with overlap, capped with a "+N" overflow indicator
+<AvatarGroup max={3}>
+  <Avatar name="Jane Doe" />
+  <Avatar name="Carlos Diaz" />
+  <Avatar name="Amy Lin" />
+  <Avatar name="Sam Patel" />
+</AvatarGroup>
+```
+
+**Avatar props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `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) |
+| `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) |
+
+**AvatarGroup props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | `Avatar` elements to stack |
+| `max` | `number` | Cap on visible avatars before collapsing the rest into a `+N` indicator |
+
+The `+N` overflow indicator is itself an `Avatar` (with `content="+N"`), so it always matches whatever the avatar circle looks like. Setting `--avatar-radius` on `AvatarGroup` (rather than per-`Avatar`) cascades to every avatar inside *and* their separator rings, so the shape stays consistent across the group.
+
+**Slots (Avatar):** `image` `fallback` `status`
+**Slots (AvatarGroup):** `item` (wrapper around each visible avatar) `overflow` (wrapper around the `+N` avatar)

package/docs/Badge.md

@@ -0,0 +1,52 @@
+# Badge
+
+**When to use:** Small count or status indicator — unread counts, notification dots, "new" markers. Use standalone, or wrap an icon/avatar/button to overlay the badge on one of its corners.
+
+**Import:** `import { Badge, BadgeStyleType, BadgePosition } from '@ahrowe/ui'`
+
+**Style variants:** `BadgeStyleType.Default` | `BadgeStyleType.Primary` (default) | `BadgeStyleType.Success` | `BadgeStyleType.Info` | `BadgeStyleType.Warn` | `BadgeStyleType.Error`
+
+**Position (when wrapping `children`):** `BadgePosition.TopRight` (default) | `BadgePosition.TopLeft` | `BadgePosition.BottomRight` | `BadgePosition.BottomLeft`
+
+```tsx
+import { Badge, BadgeStyleType } from '@ahrowe/ui';
+import { faBell } from '@fortawesome/free-solid-svg-icons';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+
+// Standalone count
+<Badge count={3} />
+
+// Caps at `max` and shows "99+"
+<Badge count={128} max={99} />
+
+// Custom content instead of a count
+<Badge content="NEW" />
+
+// Plain dot, no text
+<Badge dot styleType={BadgeStyleType.Error} />
+
+// Overlaying an icon
+<Badge count={12} styleType={BadgeStyleType.Error}>
+  <FontAwesomeIcon icon={faBell} />
+</Badge>
+
+// Hidden at 0 by default — opt in to show it
+<Badge count={0} showZero>
+  <FontAwesomeIcon icon={faBell} />
+</Badge>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `count` | `number` | Number to display. Hidden when `0` unless `showZero` is set |
+| `max` | `number` | Highest number shown before collapsing to `${max}+` (default `99`) |
+| `content` | `ReactNode` | Custom content overriding the computed `count` text |
+| `dot` | `boolean` | Render as a plain dot with no text |
+| `showZero` | `boolean` | Show the badge when `count` is `0` |
+| `styleType` | `BadgeStyleType` | Colour variant (default `Primary`) |
+| `position` | `BadgePosition` | Corner the badge attaches to when wrapping `children` (default `TopRight`) |
+| `children` | `ReactNode` | Element the badge overlays. Omit to render the badge inline on its own |
+
+**Slots:** `badge`

package/docs/Button.md

@@ -49,4 +49,25 @@ import { faSave } from '@fortawesome/free-solid-svg-icons';
 | `disabled` | `boolean` | |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
 
+**Theming (default style):** the `Default` style is transparent text-coloured by default. Override it theme-wide (or per button via `style`) without touching `Primary`/`Delete`:
+
+- `--button-default-background` — fill (default transparent)
+- `--button-default-color` — text colour (default `var(--text-color)`)
+- `--button-default-border` — full `border` shorthand, e.g. `1px solid var(--border-color)` (default a transparent `1px` border)
+
+Every button reserves a transparent `1px` border, so switching `--button-default-border` on never shifts layout or changes button height. See [ThemeProvider.md](ThemeProvider.md).
+
+```tsx
+// Outlined default buttons across the app
+const theme: Theme = {
+  id: 'brand',
+  variables: { '--button-default-border': '1px solid var(--border-color)' },
+};
+
+// Or one-off via style
+<Button style={{ '--button-default-border': '1px solid var(--border-color)' } as React.CSSProperties}>
+  Cancel
+</Button>
+```
+
 **Slots:** `background` `content` `loadingContainer` `label`

package/docs/CLAUDE.md

@@ -95,6 +95,8 @@ Slot keys per component are documented in each component's doc file below.
 @Accordion.md
 @ActionButtons.md
 @ActionIcon.md
+@Avatar.md
+@Badge.md
 @BodyEnd.md
 @Button.md
 @Card.md
@@ -118,6 +120,7 @@ Slot keys per component are documented in each component's doc file below.
 @InputDropdown.md
 @InteractableDiv.md
 @KanbanBoard.md
+@KlipyPicker.md
 @Loading.md
 @Modal.md
 @NumberInput.md
@@ -129,10 +132,11 @@ Slot keys per component are documented in each component's doc file below.
 @RoomViewer.md
 @ScrollbarProvider.md
 @SearchInput.md
+@Skeleton.md
 @Stepper.md
 @Sticky.md
+@Switch.md
 @TabHeader.md
-@TenorPicker.md
 @Textarea.md
 @ThemeProvider.md
 @TimeInput.md

package/docs/{TenorPicker.md → KlipyPicker.md}

@@ -1,17 +1,17 @@
-# TenorPicker
+# KlipyPicker
 
-**When to use:** GIF picker backed by the Tenor API — chat reactions, message composers, content authoring tools. Renders inline by default; pass `isModal` to open inside a `Modal`.
+**When to use:** GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools. Renders inline by default; pass `isModal` to open inside a `Modal`.
 
-**Import:** `import { TenorPicker } from '@ahrowe/ui'`
+**Import:** `import { KlipyPicker } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Tenor API token — the component ships with a default key, but supply your own `token` prop for production use.
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Klipy API token — the component ships with a default key, but supply your own `token` prop for production use.
 
 ```tsx
-import { TenorPicker } from '@ahrowe/ui';
+import { KlipyPicker } from '@ahrowe/ui';
 
 // Inline picker
-<TenorPicker
-  token={process.env.TENOR_API_KEY}
+<KlipyPicker
+  token={process.env.KLIPY_API_KEY}
   onSelect={(preview) => {
     if (preview) {
       attachGif(preview.media_formats.gif.url);
@@ -20,8 +20,8 @@ import { TenorPicker } from '@ahrowe/ui';
 />
 
 // Inside a modal trigger
-<TenorPicker
-  token={process.env.TENOR_API_KEY}
+<KlipyPicker
+  token={process.env.KLIPY_API_KEY}
   isModal
   selected={currentGifId}
   onSelect={async (preview) => {
@@ -34,8 +34,8 @@ import { TenorPicker } from '@ahrowe/ui';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `token` | `string` | Tenor API key (defaults to a built-in demo key — replace in production) |
+| `token` | `string` | Klipy API key (defaults to a built-in demo key — replace in production) |
 | `isModal` | `boolean` | Render the picker inside a `Modal` instead of inline |
 | `selected` | `string \| null` | Currently selected GIF id (for visual highlight) |
-| `onSelect` | `(preview: TenorResult \| null) => void \| Promise<void>` | Fires when a GIF is picked; `null` when cleared |
+| `onSelect` | `(preview: KlipyResult \| null) => void \| Promise<void>` | Fires when a GIF is picked; `null` when cleared |
 | `className` | `string` | Root element class |

package/docs/Skeleton.md

@@ -0,0 +1,50 @@
+# Skeleton
+
+**When to use:** Content-shaped loading placeholder, shown while real content is being fetched — more polished than a spinner for content-heavy pages (lists, cards, profile headers). Pick the `variant` that matches the shape of what's loading.
+
+**Import:** `import { Skeleton, SkeletonVariant, SkeletonAnimation } from '@ahrowe/ui'`
+
+**Style variants:** `SkeletonVariant.Text` (default) | `SkeletonVariant.Circle` | `SkeletonVariant.Rectangular`
+
+**Animation:** `SkeletonAnimation.Shimmer` (default) | `SkeletonAnimation.Pulse` | `SkeletonAnimation.None`
+
+```tsx
+import { Skeleton, SkeletonVariant, SkeletonAnimation } from '@ahrowe/ui';
+
+// Text line (default variant, full-width, ~1 line of text tall)
+<Skeleton />
+
+// Multiple stacked lines — the last one renders narrower, like a paragraph
+<Skeleton variant={SkeletonVariant.Text} lines={3} />
+
+// Circle — set width/height to match what it stands in for (e.g. an Avatar)
+<Skeleton variant={SkeletonVariant.Circle} style={{ width: 48, height: 48 }} />
+
+// Rectangular block — images, cards, charts
+<Skeleton variant={SkeletonVariant.Rectangular} style={{ width: '100%', height: 120 }} />
+
+// Animation
+<Skeleton variant={SkeletonVariant.Text} animation={SkeletonAnimation.Pulse} />
+
+// Composed — a typical card placeholder
+<div style={{ display: 'flex', gap: 12 }}>
+  <Skeleton variant={SkeletonVariant.Circle} style={{ width: 48, height: 48 }} />
+  <div style={{ flex: 1, display: 'flex', flexDirection: 'column', gap: 8 }}>
+    <Skeleton variant={SkeletonVariant.Text} style={{ width: '40%' }} />
+    <Skeleton variant={SkeletonVariant.Text} lines={2} />
+  </div>
+</div>
+```
+
+**Sizing:** there's no dedicated size prop — set `width`/`height` via `style`/`className` to match the content being replaced. `SkeletonVariant.Text` defaults to `height: 1em` and `width: 100%` since that's almost always what's wanted for a text placeholder.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `variant` | `SkeletonVariant` | Placeholder shape (default `Text`) |
+| `animation` | `SkeletonAnimation` | Loading animation (default `Shimmer`); respects `prefers-reduced-motion` |
+| `lines` | `number` | Stacked lines, `SkeletonVariant.Text` only (default `1`); the last line is narrower |
+| `className` / `style` | | Root element |
+
+**Slots:** `line` (each stacked line when `lines > 1`)

package/docs/Switch.md

@@ -0,0 +1,50 @@
+# Switch
+
+**When to use:** Sliding boolean toggle — settings panels, feature flags, preference lists. Same shape as `Checkbox` but visually a track + thumb; prefer `Switch` when the effect is immediate (e.g. enabling a setting) and `Checkbox` for selections inside a form that gets submitted.
+
+**Import:** `import { Switch } from '@ahrowe/ui'`
+
+```tsx
+import { Switch, FormValidator } from '@ahrowe/ui';
+
+// Uncontrolled with callback
+<Switch
+  label="Dark mode"
+  selected={darkMode}
+  onToggle={(isOn) => setDarkMode(isOn)}
+/>
+
+// With FormValidator
+const notifyValidator = new FormValidator(false);
+<Switch label="Email notifications" formValidator={notifyValidator} />
+
+// Disabled
+<Switch label="Locked setting" selected={true} disabled />
+
+// Resize — all dimensions are in `em`, so font-size scales the whole switch
+<Switch label="Large" selected={true} onToggle={() => {}} style={{ fontSize: '20px' }} />
+
+// Or resize just the track via the slot, independent of the label
+<Switch
+  label="Custom track size"
+  selected={true}
+  onToggle={() => {}}
+  styles={{ track: { width: '3em', height: '1.5em' } }}
+/>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Text beside the switch |
+| `selected` | `boolean` | On/off state |
+| `onToggle` | `(isToggled: boolean, event?) => void` | Change handler |
+| `formValidator` | `FormValidator` | Connects to form validation |
+| `disabled` | `boolean` | |
+| `children` | `ReactNode` | Custom label content (overrides `label`) |
+| `tabIndex` | `number` | |
+
+**Sizing:** the track and thumb are dimensioned in `em`, so the whole switch scales with the inherited `font-size` — no dedicated size prop. Use `style={{ fontSize: ... }}` to scale everything together, or the `track`/`thumb` slots (`classNames`/`styles`) to resize just those parts.
+
+**Slots:** `track` `thumb` `label`

package/docs/ThemeProvider.md

@@ -69,6 +69,7 @@ interface Theme {
 | `--border-color` | Borders and dividers |
 | `--error-color` / `--success-color` / `--warn-color` / `--info-color` | Semantic colours |
 | `--default-border-radius` | Border radii |
+| `--avatar-radius` | `Avatar` corner radius — falls back to `--default-border-radius` when unset (set to `50%` theme-wide for fully circular avatars) |
 | `--card-shadow` | Elevation shadows |
 
 **Key props:**

package/package.json

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

package/dist/types/package/common/tenorPicker/components/gifPreview/gifPreview.types.d.ts

@@ -1,7 +0,0 @@
-import { TenorResult } from '../../../../services/tenor.service';
-export interface GifPreviewProps {
-    className?: string;
-    previewItems?: TenorResult[];
-    onSelect?: (preview: TenorResult) => void;
-    onLoadAdditional?: () => void;
-}

package/dist/types/package/common/tenorPicker/index.d.ts

@@ -1,2 +0,0 @@
-export { default } from './tenorPicker';
-export * from './tenorPicker.types';

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

@@ -1,3 +0,0 @@
-import { ReactElement } from 'react';
-import { TenorPickerProps } from './tenorPicker.types';
-export default function TenorPicker({ className, token, isModal, onSelect, selected, }: TenorPickerProps): ReactElement;

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

@@ -1,8 +0,0 @@
-import { TenorResult } from '../../services/tenor.service';
-export interface TenorPickerProps {
-    className?: string;
-    token?: string;
-    isModal?: boolean;
-    onSelect?: (preview: TenorResult | null) => void | Promise<void>;
-    selected?: string | null;
-}

package/dist/types/package/services/tenor.service.d.ts

@@ -1,2 +0,0 @@
-export { default } from './tenorService';
-export type { TenorResult, TenorMediaFormat } from './tenorService';