srcdev-nuxt-components 9.1.43 → 9.1.44

package/.claude/skills/components/display-avatar.md

@@ -0,0 +1,187 @@
+# DisplayAvatar Component
+
+## Overview
+
+`DisplayAvatar` renders a circular avatar — either an image (via `NuxtImg`) or a text fallback showing initials derived from the `alt` prop. Optionally wraps in a `DisplayChip` to show a status indicator badge.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:style-class-passthrough`.
+
+| Prop (template form)       | Type                                      | Default  | Notes                                                              |
+| -------------------------- | ----------------------------------------- | -------- | ------------------------------------------------------------------ |
+| `as`                       | `string \| object`                        | `"span"` | Root element tag. Ignored when `chip` is set.                      |
+| `src`                       | `string`                                  | —        | Image URL. Renders `NuxtImg` when set; fallback text otherwise.   |
+| `alt`                       | `string`                                  | —        | Alt text for the image; also used to derive initials.             |
+| `text`                      | `string`                                  | —        | Override the auto-derived initials with an explicit string.       |
+| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Controls width, height, and font-size.                            |
+| `chip`                      | `boolean \| DisplayChipConfig`           | —        | Add a status chip. `true` uses defaults; pass a config object to customise. |
+| `:style-class-passthrough`  | `string \| string[]`                      | `[]`     | Extra CSS classes on the root element.                            |
+
+### Size dimensions
+
+| Size | Diameter | Font size |
+| ---- | -------- | --------- |
+| `xs` | 24px     | 0.75rem   |
+| `s`  | 32px     | 0.875rem  |
+| `md` | 40px     | 1rem      |
+| `lg` | 48px     | 1.125rem  |
+| `xl` | 56px     | 1.25rem   |
+
+---
+
+## Slots
+
+| Slot      | Purpose                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `default` | Replaces the auto image/fallback content entirely.                  |
+| `icon`    | Appended inside the avatar (e.g. an icon overlay over the image). |
+
+---
+
+## Fallback text logic
+
+When `src` is not set, a `<span>` renders the fallback value:
+
+1. `text` prop — used as-is if provided.
+2. `alt` initials — first character of each word, capped at two characters.
+3. Empty string — if neither is set.
+
+```
+alt="John Doe"     → "JD"
+alt="Alice"        → "A"
+alt="Alice Bob C"  → "AB"
+text="?"           → "?"
+```
+
+---
+
+## Usage examples
+
+### Image avatar
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  size="lg"
+/>
+```
+
+### Initials fallback
+
+```vue
+<DisplayAvatar alt="Jane Smith" size="md" />
+<!-- renders: "JS" -->
+```
+
+### Custom text fallback
+
+```vue
+<DisplayAvatar text="?" size="xs" />
+```
+
+### Custom root element
+
+```vue
+<DisplayAvatar as="div" alt="Jane Smith" />
+```
+
+### With a status chip (default config)
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  :chip="true"
+/>
+```
+
+Default chip config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`.
+
+### With a custom chip
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  :chip="{
+    size: '16px',
+    maskWidth: '2px',
+    offset: '4px',
+    angle: '45deg'
+  }"
+/>
+```
+
+Full `DisplayChipConfig` shape (pass directly as the `chip` value):
+
+```ts
+interface DisplayChipConfig {
+  size: string       // chip diameter, e.g. "12px"
+  maskWidth: string  // cutout ring width, e.g. "4px"
+  offset: string     // distance from avatar edge, e.g. "0px"
+  angle: string      // position around avatar (0–360deg), e.g. "45deg"
+  icon?: string      // Iconify icon name
+  label?: string     // short text (max 3 characters)
+}
+```
+
+### Default slot override
+
+```vue
+<DisplayAvatar size="xl">
+  <template #default>
+    <img src="/images/profile.jpg" alt="Jane Smith" class="avatar-image" />
+  </template>
+</DisplayAvatar>
+```
+
+### Icon slot
+
+```vue
+<DisplayAvatar alt="Jane Smith">
+  <template #icon>
+    <Icon name="bi:check-circle-fill" class="avatar-icon" />
+  </template>
+</DisplayAvatar>
+```
+
+---
+
+## Local style override scaffold
+
+```vue
+<DisplayAvatar
+  alt="Jane Smith"
+  :style-class-passthrough="['profile-avatar']"
+/>
+
+<style>
+/* ─── DisplayAvatar local overrides ────────────────────────────────
+   Scope by your wrapper class, then nest .display-avatar directly.
+   No :deep() needed (component styles are unscoped).
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.my-page-section {
+  .display-avatar {
+    &.profile-avatar {
+      /* custom overrides */
+    }
+  }
+}
+</style>
+```
+
+See [component-local-style-override.md](../component-local-style-override.md) for the full pattern.
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- When `chip` is set, the root element becomes `DisplayChip` and the `as` prop is ignored.
+- `class` and `style` are **not** declared as explicit props — they fall through to the root element automatically via Vue's attribute inheritance (`inheritAttrs: true`). Do not re-add them as props; doing so pulls them out of `$attrs` and breaks automatic inheritance.
+- `NuxtImg` is used for the image, so `@nuxt/image` must be installed in the consuming app.

package/.claude/skills/components/display-chip.md

@@ -0,0 +1,213 @@
+# DisplayChip Component
+
+## Overview
+
+`DisplayChip` renders a small status indicator dot (or icon/label badge) that is absolutely positioned on a parent element using CSS trigonometric functions. It works by applying a radial-gradient mask to the parent's content, creating a clean cutout behind the chip. Supports circle and square parent shapes.
+
+Used directly for standalone chip overlays, and internally by `DisplayAvatar` when its `chip` prop is set.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:style-class-passthrough`.
+
+| Prop (template form)       | Type                       | Default    | Notes                                              |
+| -------------------------- | -------------------------- | ---------- | -------------------------------------------------- |
+| `tag`                      | `"div" \| "span"`          | `"span"`   | Root element tag.                                  |
+| `shape`                    | `"circle" \| "square"`     | `"circle"` | Affects position maths — must match the parent shape. |
+| `:config`                  | `DisplayChipConfig`        | see below  | Controls chip geometry and optional content.       |
+| `:style-class-passthrough` | `string \| string[]`       | `[]`       | Extra CSS classes — use for status colour variants. |
+
+### DisplayChipConfig
+
+```ts
+interface DisplayChipConfig {
+  size: string       // chip dot diameter, e.g. "12px"
+  maskWidth: string  // cutout ring width around the chip, e.g. "4px"
+  offset: string     // extra distance from the parent edge, e.g. "0px"
+  angle: string      // position around the parent (0–360deg), e.g. "45deg"
+  icon?: string      // Iconify icon name rendered inside the chip
+  label?: string     // short text rendered inside the chip (max 3 characters)
+}
+```
+
+Default config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`.
+
+### Angle reference
+
+| Angle    | Position     |
+| -------- | ------------ |
+| `0deg`   | Top          |
+| `45deg`  | Top-right    |
+| `90deg`  | Right        |
+| `135deg` | Bottom-right |
+| `180deg` | Bottom       |
+| `225deg` | Bottom-left  |
+| `270deg` | Left         |
+| `315deg` | Top-left     |
+
+---
+
+## Status colours
+
+Apply status via `styleClassPassthrough` — the component has built-in colour variants:
+
+| Class      | Colour                  |
+| ---------- | ----------------------- |
+| (none)     | `slategrey` (offline)   |
+| `online`   | `rgb(0, 255, 135)`      |
+| `idle`     | `rgb(255, 185, 51)`     |
+| `dnd`      | `rgb(255, 40, 80)`      |
+
+```vue
+<DisplayChip :style-class-passthrough="['online']">...</DisplayChip>
+```
+
+---
+
+## Label constraints
+
+- Max 3 characters. Longer values are silently truncated with a `console.warn`.
+- Font-size scales automatically with chip size via `--_font-size-adjust`:
+  - 1 char → `0.7 × size`
+  - 2 chars → `0.6 × size`
+  - 3 chars → `0.5 × size`
+
+---
+
+## Slots
+
+| Slot      | Purpose                                    |
+| --------- | ------------------------------------------ |
+| `default` | The host element the chip is positioned on. Must be a single block element. |
+
+---
+
+## Usage examples
+
+### Simple status dot on a circular avatar
+
+```vue
+<DisplayChip
+  shape="circle"
+  :config="{ size: '12px', maskWidth: '4px', offset: '0px', angle: '45deg' }"
+  :style-class-passthrough="['online']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+```
+
+### Status dot on a square card thumbnail
+
+```vue
+<DisplayChip
+  shape="square"
+  :config="{ size: '10px', maskWidth: '3px', offset: '2px', angle: '135deg' }"
+  :style-class-passthrough="['idle']"
+>
+  <img src="/thumbnail.jpg" alt="Card thumbnail" />
+</DisplayChip>
+```
+
+### With an icon inside the chip
+
+```vue
+<DisplayChip
+  :config="{ size: '16px', maskWidth: '4px', offset: '0px', angle: '45deg', icon: 'bi:check-circle-fill' }"
+  :style-class-passthrough="['online']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+```
+
+### With a label inside the chip
+
+```vue
+<!-- 1–3 characters only; longer values are truncated with a warning -->
+<DisplayChip
+  :config="{ size: '16px', maskWidth: '4px', offset: '0px', angle: '45deg', label: '+2' }"
+  :style-class-passthrough="['dnd']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+```
+
+### Reactive config (QA panel / form pattern)
+
+```vue
+<script setup lang="ts">
+import type { DisplayChipConfig } from 'srcdev-nuxt-components/types/components'
+
+const size = ref(12)
+const angle = ref(45)
+
+const chipConfig = computed((): DisplayChipConfig => ({
+  size: `${size.value}px`,
+  maskWidth: '4px',
+  offset: '0px',
+  angle: `${angle.value}deg`,
+}))
+</script>
+
+<template>
+  <DisplayChip shape="circle" :config="chipConfig" :style-class-passthrough="['online']">
+    <div class="avatar">SRC</div>
+  </DisplayChip>
+</template>
+```
+
+### Via DisplayAvatar (recommended for avatar use cases)
+
+Prefer `DisplayAvatar` with its `chip` prop over wiring `DisplayChip` directly:
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  :chip="{ size: '12px', maskWidth: '4px', offset: '0px', angle: '45deg' }"
+  :style-class-passthrough="['online']"
+/>
+```
+
+See [display-avatar.md](./display-avatar.md) for the full API.
+
+---
+
+## Local style override scaffold
+
+```vue
+<DisplayChip
+  :config="chipConfig"
+  :style-class-passthrough="['my-chip']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+
+<style>
+/* ─── DisplayChip local overrides ──────────────────────────────────
+   Scope by your wrapper class, then nest .display-chip-core directly.
+   No :deep() needed (component styles are unscoped).
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.my-page-section {
+  .display-chip-core {
+    &.my-chip {
+      /* override colour vars, e.g. */
+      --color-online: hotpink;
+    }
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- `shape` must match the actual shape of the slot content — the position maths differs between `circle` (radius-based) and `square` (clamped corner-aware).
+- `config` values are geometric inputs to CSS `calc(cos())` / `calc(sin())` expressions. Pass them as strings with units (`"12px"`, `"45deg"`), not plain numbers.
+- The chip dot is rendered via `::after` pseudo-element; icon and label sit above it at `z-index: 2`.
+- The mask cutout is applied to all direct children of `.display-chip-core` except `.chip-icon` and `.chip-label` — ensure the host element is a direct child.
+- `DisplayChipConfig` and `DisplayChipProps` are both exported from the layer types. Use `DisplayChipConfig` when passing geometry values (the `config` prop). Use `DisplayChipProps` only if you need to pass the full component prop set (e.g. when building a wrapper component).

package/.claude/skills/index.md

@@ -78,6 +78,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── capture-qr-code.md      — CaptureQrCode: live camera scanner, error state, visibility/route/KeepAlive lifecycle, media stream cleanup
     ├── decode-qr-code.md       — DecodeQrCode: file picker + drag-and-drop image decoder, shared results list, CSS override points
     ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-min-col-size/gap tokens, semantic tag + aria
+    ├── display-avatar.md       — DisplayAvatar: circular avatar with image/initials fallback, size variants, chip badge, icon slot, styleClassPassthrough
+    ├── display-chip.md         — DisplayChip: status indicator chip overlay, CSS trig positioning, circle/square shapes, status colours, icon/label content
     ├── carousel-flip.md        — CarouselFlip: FLIP-animated carousel, carouselDataIds slot API, buttonLayout variants (sides/controls-flanking/controls-grouped-right/overlay), CSS tokens
     └── samaritan-prompt-mixed.md — SamaritanPromptMixed: animated text prompt, typewriter/word-pulse effects, MessageConfig API, aria-live accessibility, CSS tokens
 ```

package/app/components/01.atoms/display-avatar/DisplayAvatar.vue

@@ -0,0 +1,130 @@
+<template>
+  <component
+    :is="props.chip ? DisplayChip : as"
+    v-bind="
+      props.chip
+        ? typeof props.chip === 'object'
+          ? { tag: chipTag, config: props.chip }
+          : { tag: chipTag, config: chipDefaultConfig }
+        : {}
+    "
+    class="display-avatar"
+    :class="[size, elementClasses]"
+    :style-class-passthrough="elementClasses"
+  >
+    <slot name="default">
+      <NuxtImg v-if="src" :src :alt="alt || 'Avatar'" width="100%" height="100%" class="avatar-image" />
+      <span v-else>{{ fallback }}</span>
+    </slot>
+    <slot name="icon"></slot>
+  </component>
+</template>
+
+<script setup lang="ts">
+import DisplayChip from "../../02.molecules/display-chip/DisplayChip.vue";
+import type { DisplayChipConfig } from "~/types/components";
+
+interface Props {
+  as?: string | object;
+  src?: string;
+  alt?: string;
+  text?: string;
+  size?: "xs" | "s" | "md" | "lg" | "xl" | string;
+  chip?: boolean | DisplayChipConfig;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  as: "span",
+  src: undefined,
+  alt: undefined,
+  text: undefined,
+  size: "md",
+  chip: undefined,
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses, updateElementClasses } = useStyleClassPassthrough(
+  props.styleClassPassthrough
+);
+
+if (props.chip && typeof props.chip === "object" && !("styleClassPassthrough" in props.chip)) {
+  updateElementClasses(["display-avatar", props.size]);
+}
+
+const fallback = computed(
+  () =>
+    props.text ||
+    (props.alt || "")
+      .split(" ")
+      .map((word) => word.charAt(0))
+      .join("")
+      .substring(0, 2)
+);
+
+const chipDefaultConfig: DisplayChipConfig = {
+  size: "12px",
+  maskWidth: "4px",
+  offset: "0px",
+  angle: "90deg",
+};
+
+const chipTag = computed((): "div" | "span" => (props.as === "div" || props.as === "span" ? props.as : "span"));
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .display-avatar {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 50%;
+    color: var(--slate-03);
+
+    isolation: isolate;
+
+    &.xs {
+      width: 24px;
+      height: 24px;
+      font-size: 0.75rem;
+    }
+    &.s {
+      width: 32px;
+      height: 32px;
+      font-size: 0.875rem;
+    }
+    &.md {
+      width: 40px;
+      height: 40px;
+      font-size: 1rem;
+    }
+    &.lg {
+      width: 48px;
+      height: 48px;
+      font-size: 1.125rem;
+    }
+    &.xl {
+      width: 56px;
+      height: 56px;
+      font-size: 1.25rem;
+    }
+
+    .avatar-image {
+      width: 100%;
+      border-radius: 50%;
+      object-fit: cover;
+    }
+
+    .avatar-icon {
+      font-size: 24px;
+    }
+  }
+}
+</style>

package/app/components/{display-avatar → 01.atoms/display-avatar}/stories/DisplayAvatar.stories.ts

@@ -5,6 +5,14 @@ export default {
   title: "Components/UI/DisplayAvatar",
   component: StorybookComponent,
   argTypes: {
+    size: {
+      control: { type: "inline-radio" },
+      options: ["xs", "s", "md", "lg", "xl"],
+      description: "Avatar size",
+      table: {
+        category: "Avatar",
+      },
+    },
     src: {
       control: { type: "text" },
       description: "Avatar image source URL",
@@ -61,6 +69,7 @@ export default {
     },
   },
   args: {
+    size: "md",
     src: "https://github.com/srcdev.png",
     alt: "SrcDev Avatar",
     chipSize: 12,
@@ -77,7 +86,9 @@ const Template: StoryFn<typeof StorybookComponent> = (args) => ({
     return { args };
   },
   template: `
+    <div style="display: flex; align-items: center; justify-content: center; height: 100vh;">
     <StorybookComponent
+      :size="args.size"
       :src="args.src"
       :alt="args.alt"
       :chip="{
@@ -88,6 +99,7 @@ const Template: StoryFn<typeof StorybookComponent> = (args) => ({
       }"
       :style-class-passthrough="args.styleClassPassthrough"
     />
+    </div>
   `,
 });