@noxlovette/material 0.3.3 → 0.4.1

package/dist/components/misc/Avatar.stories.svelte

@@ -53,3 +53,11 @@
 <Story name="Clickable" asChild>
   <Avatar seed="clickable" onclick={() => console.log('Avatar clicked')} />
 </Story>
+
+<Story name="Animated" asChild>
+  <div class="flex items-end gap-4">
+    <Avatar seed="alice" dicebearStyle="gaze" tags={['animation']} />
+    <Avatar seed="bob" dicebearStyle="shapes" tags={['animation']} />
+    <Avatar seed="carol" dicebearStyle="blobs" tags={['animation']} />
+  </div>
+</Story>

package/dist/components/misc/Avatar.svelte

@@ -8,6 +8,8 @@ Avatars can be used to represent people or objects.
   import { Avatar as AvatarPrimitive } from 'bits-ui';
   import { Layer } from '../../utils/index.js';
   import { avatar } from './theme.js';
+  import { DicebearAvatarBuilder } from './DicebearAvatarBuilder.js';
+  import { getMaterialAvatarPalette } from './materialAvatarPalette.js';
   import type { AvatarProps } from './types.js';
 
   let {
@@ -15,6 +17,8 @@ Avatars can be used to represent people or objects.
     alt = 'User avatar',
     seed = 'ogonek',
     dicebearStyle = 'shapes',
+    backgroundColor,
+    tags,
     size = 'lg',
     loadingStatus = $bindable('loading'),
     class: className,
@@ -22,23 +26,40 @@ Avatars can be used to represent people or objects.
     ...rest
   }: AvatarProps = $props();
 
-  const materialPalette = ['e8f0fe', 'e8f5e9', 'fff7e6', 'fde7ec', 'e3f2fd'];
   const sizeMap = {
+    xxs: 20,
+    xs: 32,
     sm: 48,
     md: 72,
     lg: 96
   } as const;
 
-  const generatedAvatar = $derived.by(() => {
+  let generatedAvatar = $state('');
+
+  $effect(() => {
     const sizePx = sizeMap[size ?? 'lg'] ?? 96;
-    const params = new URLSearchParams({
-      seed,
-      size: String(sizePx),
-      radius: '50',
-      backgroundColor: materialPalette.join(',')
+    const currentSeed = seed;
+    const currentStyle = dicebearStyle ?? 'shapes';
+    const palette = backgroundColor ?? getMaterialAvatarPalette();
+    const currentTags = tags;
+    let cancelled = false;
+
+    const builder = new DicebearAvatarBuilder(currentStyle)
+      .seed(currentSeed)
+      .size(sizePx)
+      .borderRadius(50)
+      .background(palette);
+
+    if (currentTags) builder.tags(currentTags);
+
+    builder.toDataUri().then((uri) => {
+      if (cancelled) return;
+      generatedAvatar = uri;
     });
 
-    return `https://api.dicebear.com/9.x/${dicebearStyle}/svg?${params.toString()}`;
+    return () => {
+      cancelled = true;
+    };
   });
 
   const { root, image, fallback, button } = $derived(avatar({ size }));
@@ -54,7 +75,9 @@ Avatars can be used to represent people or objects.
         <AvatarPrimitive.Image {src} {alt} class={image()} />
       {/if}
       <AvatarPrimitive.Fallback class={fallback()}>
-        <img src={generatedAvatar} {alt} class={image()} />
+        {#if generatedAvatar}
+          <img src={generatedAvatar} {alt} class={image()} />
+        {/if}
       </AvatarPrimitive.Fallback>
     </AvatarPrimitive.Root>
   </button>
@@ -64,7 +87,9 @@ Avatars can be used to represent people or objects.
       <AvatarPrimitive.Image {src} {alt} class={image()} />
     {/if}
     <AvatarPrimitive.Fallback class={fallback()}>
-      <img src={generatedAvatar} {alt} class={image()} />
+      {#if generatedAvatar}
+        <img src={generatedAvatar} {alt} class={image()} />
+      {/if}
     </AvatarPrimitive.Fallback>
   </AvatarPrimitive.Root>
 {/if}

package/dist/components/misc/DicebearAvatarBuilder.d.ts

@@ -0,0 +1,59 @@
+import { Avatar as DicebearAvatar } from '@dicebear/core';
+import type { DicebearStyleName } from './dicebearStyles.js';
+export type DicebearFlip = 'none' | 'horizontal' | 'vertical' | 'both';
+export type DicebearColorFill = 'solid' | 'linear' | 'radial';
+export type DicebearColorOrder = 'random' | 'fixed';
+/** The raw options bag passed to DiceBear's `Avatar` constructor. */
+export type DicebearAvatarOptions = Record<string, unknown>;
+/**
+ * Fluent builder around DiceBear's `Style` + `Avatar` SDK classes
+ * (https://www.dicebear.com/customize/options/). The style definition is only
+ * lazily imported once a terminal method (`build`/`toDataUri`/`toSvg`) is called.
+ *
+ * Covers the generic options every style accepts (seed, transform, background,
+ * typography) as named methods; use `.option()`/`.options()` for options specific
+ * to the chosen style's own components (e.g. `hairColor`, `eyesVariant`), which
+ * can't be named generically — see the selected style's `OptionsDescriptor`.
+ *
+ * @example
+ * ```ts
+ * const uri = await new DicebearAvatarBuilder('lorelei')
+ *   .seed('alice')
+ *   .size(96)
+ *   .background(['b6e3f4', 'c0aede'])
+ *   .option('hairColor', ['2c1b18'])
+ *   .toDataUri();
+ * ```
+ */
+export declare class DicebearAvatarBuilder {
+    #private;
+    constructor(styleName: DicebearStyleName);
+    seed(seed: string): this;
+    size(px: number): this;
+    idRandomization(enabled?: boolean): this;
+    title(text: string): this;
+    font(family: string | string[], weight?: number): this;
+    flip(value: DicebearFlip): this;
+    rotate(degrees: number): this;
+    scale(factor: number): this;
+    borderRadius(radius: number): this;
+    translate(x: number, y: number): this;
+    background(colors: string[], fill?: DicebearColorFill, order?: DicebearColorOrder): this;
+    backgroundGradient(stops: number, angle: number): this;
+    /**
+     * Filters which variant a style picks by tag — currently DiceBear's only tag is
+     * `'animation'`, which opts a supporting style (e.g. `gaze`, `shapes`, `blobs`) into its
+     * animated variants; prefix with `!` (e.g. `'!animation'`) to force the static variant
+     * instead. A no-op for styles that don't define the tag.
+     * @see https://www.dicebear.com/guides/filter-variants-with-tags
+     */
+    tags(tags: string[]): this;
+    /** Escape hatch for an option specific to the chosen style (e.g. `hairColor`, `eyesVariant`). */
+    option(key: string, value: unknown): this;
+    /** Merges an arbitrary options object in, e.g. one collected from user input. */
+    options(values: DicebearAvatarOptions): this;
+    /** Resolves the style definition and constructs the underlying `Avatar` instance. */
+    build(): Promise<DicebearAvatar>;
+    toDataUri(): Promise<string>;
+    toSvg(): Promise<string>;
+}

package/dist/components/misc/DicebearAvatarBuilder.js

@@ -0,0 +1,115 @@
+import { Avatar as DicebearAvatar } from '@dicebear/core';
+import { loadDicebearStyle } from './dicebearStyles.js';
+/**
+ * Fluent builder around DiceBear's `Style` + `Avatar` SDK classes
+ * (https://www.dicebear.com/customize/options/). The style definition is only
+ * lazily imported once a terminal method (`build`/`toDataUri`/`toSvg`) is called.
+ *
+ * Covers the generic options every style accepts (seed, transform, background,
+ * typography) as named methods; use `.option()`/`.options()` for options specific
+ * to the chosen style's own components (e.g. `hairColor`, `eyesVariant`), which
+ * can't be named generically — see the selected style's `OptionsDescriptor`.
+ *
+ * @example
+ * ```ts
+ * const uri = await new DicebearAvatarBuilder('lorelei')
+ *   .seed('alice')
+ *   .size(96)
+ *   .background(['b6e3f4', 'c0aede'])
+ *   .option('hairColor', ['2c1b18'])
+ *   .toDataUri();
+ * ```
+ */
+export class DicebearAvatarBuilder {
+    #styleName;
+    #options = {};
+    constructor(styleName) {
+        this.#styleName = styleName;
+    }
+    seed(seed) {
+        this.#options.seed = seed;
+        return this;
+    }
+    size(px) {
+        this.#options.size = px;
+        return this;
+    }
+    idRandomization(enabled = true) {
+        this.#options.idRandomization = enabled;
+        return this;
+    }
+    title(text) {
+        this.#options.title = text;
+        return this;
+    }
+    font(family, weight) {
+        this.#options.fontFamily = Array.isArray(family) ? family : [family];
+        if (weight !== undefined)
+            this.#options.fontWeight = weight;
+        return this;
+    }
+    flip(value) {
+        this.#options.flip = value;
+        return this;
+    }
+    rotate(degrees) {
+        this.#options.rotate = degrees;
+        return this;
+    }
+    scale(factor) {
+        this.#options.scale = factor;
+        return this;
+    }
+    borderRadius(radius) {
+        this.#options.borderRadius = radius;
+        return this;
+    }
+    translate(x, y) {
+        this.#options.translateX = x;
+        this.#options.translateY = y;
+        return this;
+    }
+    background(colors, fill = 'solid', order = 'random') {
+        this.#options.backgroundColor = colors;
+        this.#options.backgroundColorFill = fill;
+        this.#options.backgroundColorOrder = order;
+        return this;
+    }
+    backgroundGradient(stops, angle) {
+        this.#options.backgroundColorFillStops = stops;
+        this.#options.backgroundColorAngle = angle;
+        return this;
+    }
+    /**
+     * Filters which variant a style picks by tag — currently DiceBear's only tag is
+     * `'animation'`, which opts a supporting style (e.g. `gaze`, `shapes`, `blobs`) into its
+     * animated variants; prefix with `!` (e.g. `'!animation'`) to force the static variant
+     * instead. A no-op for styles that don't define the tag.
+     * @see https://www.dicebear.com/guides/filter-variants-with-tags
+     */
+    tags(tags) {
+        this.#options.tags = tags;
+        return this;
+    }
+    /** Escape hatch for an option specific to the chosen style (e.g. `hairColor`, `eyesVariant`). */
+    option(key, value) {
+        this.#options[key] = value;
+        return this;
+    }
+    /** Merges an arbitrary options object in, e.g. one collected from user input. */
+    options(values) {
+        Object.assign(this.#options, values);
+        return this;
+    }
+    /** Resolves the style definition and constructs the underlying `Avatar` instance. */
+    async build() {
+        const style = await loadDicebearStyle(this.#styleName);
+        return new DicebearAvatar(style, this.#options);
+    }
+    async toDataUri() {
+        return (await this.build()).toDataUri();
+    }
+    async toSvg() {
+        return (await this.build()).toString();
+    }
+}

package/dist/components/misc/ThemeSettings.svelte

@@ -55,7 +55,7 @@
         type="file"
         accept="image/*"
         onchange={handleImageUpload}
-        class="file:bg-md-sys-color-primary-container file:text-md-sys-color-on-primary-container hover:file:bg-md-sys-color-primary-container/80 md-sys-typescale-body-medium file:mr-4 file:rounded-full file:border-0 file:px-4 file:py-2 file:md-sys-typescale-label-large"
+        class="file:bg-md-sys-color-primary-container file:text-md-sys-color-on-primary-container hover:file:bg-md-sys-color-primary-container/80 md-sys-typescale-body-medium file:md-sys-typescale-label-large file:mr-4 file:rounded-full file:border-0 file:px-4 file:py-2"
       />
     </div>
   </div>

package/dist/components/misc/ThemeSwitcher.svelte

@@ -8,8 +8,8 @@
 
 <div class="fixed right-4 bottom-4 z-50 hidden md:block">
   <Popover bind:open title="Theme Settings" side="top" align="end" sideOffset={16}>
-    {#snippet trigger()}
-      <FAB iconProps={{ name: 'palette' }} config="primary" />
+    {#snippet trigger(triggerProps)}
+      <FAB iconProps={{ name: 'palette' }} config="primary" {...triggerProps} />
     {/snippet}
 
     <div

package/dist/components/misc/dicebearStyles.d.ts

@@ -0,0 +1,21 @@
+import { OptionsDescriptor, Style } from '@dicebear/core';
+/**
+ * `@dicebear/core` does not publicly export its `Descriptor`/`FieldDescriptor` types (only
+ * the `OptionsDescriptor` class itself), so they're recovered structurally from its `toJSON()`
+ * return type instead of being duplicated by hand.
+ */
+export type DicebearDescriptor = ReturnType<InstanceType<typeof OptionsDescriptor>['toJSON']>;
+export type DicebearFieldDescriptor = DicebearDescriptor[string];
+/**
+ * Every style shipped by `@dicebear/styles` (v10). Kept as the single source of
+ * truth for the `DicebearStyle` type in `types.ts` — extend this list first when
+ * DiceBear adds a new style, everything else derives from it.
+ */
+export declare const DICEBEAR_STYLES: readonly ["adventurer", "adventurer-neutral", "avataaars", "avataaars-neutral", "big-ears", "big-ears-neutral", "big-smile", "blobs", "bottts", "bottts-neutral", "cameo", "clay", "constellation", "critters", "croodles", "croodles-neutral", "cutouts", "disco", "dylan", "fun-emoji", "gaze", "glass", "glyphs", "icons", "identicon", "initial-face", "initials", "landscape", "line-face", "loops", "lorelei", "lorelei-neutral", "marbles", "micah", "miniavs", "moods", "notionists", "notionists-neutral", "open-peeps", "patchwork", "personas", "pixel-art", "pixel-art-neutral", "pixelbot", "planets", "rings", "shadows", "shape-grid", "shapes", "slice", "sprouts", "squircles", "stack", "stripes", "thumbs", "toon-head", "triangles", "voxel-art", "voxel-bot", "waves", "weave"];
+export type DicebearStyleName = (typeof DICEBEAR_STYLES)[number];
+/** Lazily imports and validates a style definition, caching the resulting `Style` instance. */
+export declare function loadDicebearStyle(name: DicebearStyleName): Promise<Style>;
+/** Lazily builds the `OptionsDescriptor` JSON for a style, describing every option it accepts. */
+export declare function loadDicebearOptionsDescriptor(name: DicebearStyleName): Promise<DicebearDescriptor>;
+/** Turns a style name like `big-ears-neutral` into `Big Ears Neutral`. */
+export declare function formatDicebearStyleLabel(name: string): string;

package/dist/components/misc/dicebearStyles.js

@@ -0,0 +1,169 @@
+import { OptionsDescriptor, Style } from '@dicebear/core';
+/**
+ * Every style shipped by `@dicebear/styles` (v10). Kept as the single source of
+ * truth for the `DicebearStyle` type in `types.ts` — extend this list first when
+ * DiceBear adds a new style, everything else derives from it.
+ */
+export const DICEBEAR_STYLES = [
+    'adventurer',
+    'adventurer-neutral',
+    'avataaars',
+    'avataaars-neutral',
+    'big-ears',
+    'big-ears-neutral',
+    'big-smile',
+    'blobs',
+    'bottts',
+    'bottts-neutral',
+    'cameo',
+    'clay',
+    'constellation',
+    'critters',
+    'croodles',
+    'croodles-neutral',
+    'cutouts',
+    'disco',
+    'dylan',
+    'fun-emoji',
+    'gaze',
+    'glass',
+    'glyphs',
+    'icons',
+    'identicon',
+    'initial-face',
+    'initials',
+    'landscape',
+    'line-face',
+    'loops',
+    'lorelei',
+    'lorelei-neutral',
+    'marbles',
+    'micah',
+    'miniavs',
+    'moods',
+    'notionists',
+    'notionists-neutral',
+    'open-peeps',
+    'patchwork',
+    'personas',
+    'pixel-art',
+    'pixel-art-neutral',
+    'pixelbot',
+    'planets',
+    'rings',
+    'shadows',
+    'shape-grid',
+    'shapes',
+    'slice',
+    'sprouts',
+    'squircles',
+    'stack',
+    'stripes',
+    'thumbs',
+    'toon-head',
+    'triangles',
+    'voxel-art',
+    'voxel-bot',
+    'waves',
+    'weave'
+];
+/**
+ * One dynamic `import()` per style, written out literally (not a template
+ * expression) so every bundler — Vite, Rollup, webpack, esbuild — can
+ * statically analyze and code-split each style into its own lazily-loaded
+ * chunk. A generated/templated import here would defeat that analysis.
+ */
+// Not annotated with an explicit `StyleDefinition` return type: TS widens the enum-like string
+// literals inside each imported JSON module (e.g. element `type`) to `string`, which doesn't
+// structurally satisfy `StyleDefinition`'s literal unions. `Style` is happy to accept the
+// as-imported shape directly (it validates the real JSON against DiceBear's schema at runtime).
+const styleLoaders = {
+    adventurer: () => import('@dicebear/styles/adventurer.json'),
+    'adventurer-neutral': () => import('@dicebear/styles/adventurer-neutral.json'),
+    avataaars: () => import('@dicebear/styles/avataaars.json'),
+    'avataaars-neutral': () => import('@dicebear/styles/avataaars-neutral.json'),
+    'big-ears': () => import('@dicebear/styles/big-ears.json'),
+    'big-ears-neutral': () => import('@dicebear/styles/big-ears-neutral.json'),
+    'big-smile': () => import('@dicebear/styles/big-smile.json'),
+    blobs: () => import('@dicebear/styles/blobs.json'),
+    bottts: () => import('@dicebear/styles/bottts.json'),
+    'bottts-neutral': () => import('@dicebear/styles/bottts-neutral.json'),
+    cameo: () => import('@dicebear/styles/cameo.json'),
+    clay: () => import('@dicebear/styles/clay.json'),
+    constellation: () => import('@dicebear/styles/constellation.json'),
+    critters: () => import('@dicebear/styles/critters.json'),
+    croodles: () => import('@dicebear/styles/croodles.json'),
+    'croodles-neutral': () => import('@dicebear/styles/croodles-neutral.json'),
+    cutouts: () => import('@dicebear/styles/cutouts.json'),
+    disco: () => import('@dicebear/styles/disco.json'),
+    dylan: () => import('@dicebear/styles/dylan.json'),
+    'fun-emoji': () => import('@dicebear/styles/fun-emoji.json'),
+    gaze: () => import('@dicebear/styles/gaze.json'),
+    glass: () => import('@dicebear/styles/glass.json'),
+    glyphs: () => import('@dicebear/styles/glyphs.json'),
+    icons: () => import('@dicebear/styles/icons.json'),
+    identicon: () => import('@dicebear/styles/identicon.json'),
+    'initial-face': () => import('@dicebear/styles/initial-face.json'),
+    initials: () => import('@dicebear/styles/initials.json'),
+    landscape: () => import('@dicebear/styles/landscape.json'),
+    'line-face': () => import('@dicebear/styles/line-face.json'),
+    loops: () => import('@dicebear/styles/loops.json'),
+    lorelei: () => import('@dicebear/styles/lorelei.json'),
+    'lorelei-neutral': () => import('@dicebear/styles/lorelei-neutral.json'),
+    marbles: () => import('@dicebear/styles/marbles.json'),
+    micah: () => import('@dicebear/styles/micah.json'),
+    miniavs: () => import('@dicebear/styles/miniavs.json'),
+    moods: () => import('@dicebear/styles/moods.json'),
+    notionists: () => import('@dicebear/styles/notionists.json'),
+    'notionists-neutral': () => import('@dicebear/styles/notionists-neutral.json'),
+    'open-peeps': () => import('@dicebear/styles/open-peeps.json'),
+    patchwork: () => import('@dicebear/styles/patchwork.json'),
+    personas: () => import('@dicebear/styles/personas.json'),
+    'pixel-art': () => import('@dicebear/styles/pixel-art.json'),
+    'pixel-art-neutral': () => import('@dicebear/styles/pixel-art-neutral.json'),
+    pixelbot: () => import('@dicebear/styles/pixelbot.json'),
+    planets: () => import('@dicebear/styles/planets.json'),
+    rings: () => import('@dicebear/styles/rings.json'),
+    shadows: () => import('@dicebear/styles/shadows.json'),
+    'shape-grid': () => import('@dicebear/styles/shape-grid.json'),
+    shapes: () => import('@dicebear/styles/shapes.json'),
+    slice: () => import('@dicebear/styles/slice.json'),
+    sprouts: () => import('@dicebear/styles/sprouts.json'),
+    squircles: () => import('@dicebear/styles/squircles.json'),
+    stack: () => import('@dicebear/styles/stack.json'),
+    stripes: () => import('@dicebear/styles/stripes.json'),
+    thumbs: () => import('@dicebear/styles/thumbs.json'),
+    'toon-head': () => import('@dicebear/styles/toon-head.json'),
+    triangles: () => import('@dicebear/styles/triangles.json'),
+    'voxel-art': () => import('@dicebear/styles/voxel-art.json'),
+    'voxel-bot': () => import('@dicebear/styles/voxel-bot.json'),
+    waves: () => import('@dicebear/styles/waves.json'),
+    weave: () => import('@dicebear/styles/weave.json')
+};
+const styleCache = new Map();
+/** Lazily imports and validates a style definition, caching the resulting `Style` instance. */
+export function loadDicebearStyle(name) {
+    let cached = styleCache.get(name);
+    if (!cached) {
+        cached = styleLoaders[name]().then((mod) => new Style(mod.default));
+        styleCache.set(name, cached);
+    }
+    return cached;
+}
+const descriptorCache = new Map();
+/** Lazily builds the `OptionsDescriptor` JSON for a style, describing every option it accepts. */
+export function loadDicebearOptionsDescriptor(name) {
+    let cached = descriptorCache.get(name);
+    if (!cached) {
+        cached = loadDicebearStyle(name).then((style) => new OptionsDescriptor(style).toJSON());
+        descriptorCache.set(name, cached);
+    }
+    return cached;
+}
+/** Turns a style name like `big-ears-neutral` into `Big Ears Neutral`. */
+export function formatDicebearStyleLabel(name) {
+    return name
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}

package/dist/components/misc/index.d.ts

@@ -1,3 +1,6 @@
+export * from './DicebearAvatarBuilder.js';
+export * from './dicebearStyles.js';
+export * from './materialAvatarPalette.js';
 export * from './theme.js';
 export * from './types.js';
 export { default as Avatar } from './Avatar.svelte';

package/dist/components/misc/index.js

@@ -1,5 +1,8 @@
 // THIS FILE IS AUTO-GENERATED BY scripts/generate-components-index.ts - DO NOT EDIT MANUALLY
 // re-export TS/JS modules from this folder
+export * from './DicebearAvatarBuilder.js';
+export * from './dicebearStyles.js';
+export * from './materialAvatarPalette.js';
 export * from './theme.js';
 export * from './types.js';
 // default exports for components in this folder

package/dist/components/misc/materialAvatarPalette.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads the current app's resolved container-tier color tokens as hex strings, for use as
+ * DiceBear's `backgroundColor` option. Falls back to a neutral default outside the browser
+ * (SSR) or before the theme stylesheet has painted.
+ */
+export declare function getMaterialAvatarPalette(): string[];

package/dist/components/misc/materialAvatarPalette.js

@@ -0,0 +1,44 @@
+/**
+ * Container-tier M3 color roles (see `styles/theme/*.css`) used as a generated avatar's
+ * background. Deliberately NOT a fixed hex list: every consuming app picks its own source
+ * color (`ThemeConfig.sourceColor` in `theme.svelte.ts`), which the M3 dynamic color
+ * algorithm expands into these tokens as real `--color-md-sys-color-*` custom properties on
+ * `:root` — reading them live is what makes the avatar match that app's actual palette
+ * instead of this library's own hardcoded pastel.
+ */
+const CONTAINER_TOKENS = [
+    '--color-md-sys-color-primary-container',
+    '--color-md-sys-color-secondary-container',
+    '--color-md-sys-color-tertiary-container',
+    '--color-md-sys-color-error-container',
+    '--color-md-sys-color-surface-container-highest'
+];
+/** Used server-side, or if a token hasn't been painted yet (styles not loaded). */
+const FALLBACK_PALETTE = ['e9ddff', 'e8def8', 'ffd9e3', 'ffdad6', 'e6e0e9'];
+/** Converts the `rgb(r g b)` (or `rgb(r, g, b)`) format these tokens are always defined in to hex. */
+function rgbStringToHex(value) {
+    const channels = value.match(/\d+(?:\.\d+)?/g);
+    if (!channels || channels.length < 3)
+        return undefined;
+    return channels
+        .slice(0, 3)
+        .map((n) => Math.round(Math.max(0, Math.min(255, parseFloat(n))))
+        .toString(16)
+        .padStart(2, '0'))
+        .join('');
+}
+/**
+ * Reads the current app's resolved container-tier color tokens as hex strings, for use as
+ * DiceBear's `backgroundColor` option. Falls back to a neutral default outside the browser
+ * (SSR) or before the theme stylesheet has painted.
+ */
+export function getMaterialAvatarPalette() {
+    if (typeof window === 'undefined')
+        return FALLBACK_PALETTE;
+    const styles = getComputedStyle(document.documentElement);
+    const palette = CONTAINER_TOKENS.map((token) => {
+        const raw = styles.getPropertyValue(token).trim();
+        return raw ? rgbStringToHex(raw) : undefined;
+    }).filter((hex) => Boolean(hex));
+    return palette.length > 0 ? palette : FALLBACK_PALETTE;
+}

package/dist/components/misc/theme.d.ts

@@ -1,5 +1,11 @@
 export declare const avatar: import("tailwind-variants").TVReturnType<{
     size: {
+        xxs: {
+            root: string;
+        };
+        xs: {
+            root: string;
+        };
         sm: {
             root: string;
         };
@@ -17,6 +23,12 @@ export declare const avatar: import("tailwind-variants").TVReturnType<{
     button: string;
 }, undefined, {
     size: {
+        xxs: {
+            root: string;
+        };
+        xs: {
+            root: string;
+        };
         sm: {
             root: string;
         };
@@ -32,8 +44,14 @@ export declare const avatar: import("tailwind-variants").TVReturnType<{
     image: string;
     fallback: string;
     button: string;
-}, import("tailwind-variants").TVReturnType<{
+}, import("tailwind-variants").TVReturnTypeLike<{
     size: {
+        xxs: {
+            root: string;
+        };
+        xs: {
+            root: string;
+        };
         sm: {
             root: string;
         };
@@ -49,4 +67,4 @@ export declare const avatar: import("tailwind-variants").TVReturnType<{
     image: string;
     fallback: string;
     button: string;
-}, undefined, unknown, unknown, undefined>>;
+}>>;

package/dist/components/misc/theme.js

@@ -8,6 +8,12 @@ export const avatar = tv({
     },
     variants: {
         size: {
+            xxs: {
+                root: 'size-5'
+            },
+            xs: {
+                root: 'size-8'
+            },
             sm: {
                 root: 'size-12'
             },
@@ -20,6 +26,6 @@ export const avatar = tv({
         }
     },
     defaultVariants: {
-        size: 'lg'
+        size: 'md'
     }
 });

package/dist/components/misc/types.d.ts

@@ -1,9 +1,13 @@
 import type { Avatar as AvatarPrimitive } from 'bits-ui';
 import type { VariantProps } from 'tailwind-variants';
+import type { DicebearStyleName } from './dicebearStyles.js';
 import type { avatar } from './theme.js';
 export type AvatarVariants = VariantProps<typeof avatar>;
-/** Dicebear (https://www.dicebear.com) avatar styles available for the generated fallback avatar. */
-export type DicebearStyle = 'shapes' | 'adventurer' | 'adventurer-neutral' | 'avataaars' | 'avataaars-neutral' | 'big-ears' | 'big-ears-neutral' | 'big-smile' | 'bottts' | 'bottts-neutral' | 'croodles' | 'croodles-neutral' | 'dylan' | 'fun-emoji' | 'glass' | 'icons' | 'identicon' | 'initials' | 'lorelei' | 'lorelei-neutral' | 'micah' | 'miniavs' | 'notionists' | 'notionists-neutral' | 'open-peeps' | 'personas' | 'pixel-art' | 'pixel-art-neutral' | 'rings' | 'thumbs';
+/**
+ * Dicebear (https://www.dicebear.com) avatar styles available for the generated fallback
+ * avatar. Derived from `DICEBEAR_STYLES` in `dicebearStyles.ts` — extend the list there.
+ */
+export type DicebearStyle = DicebearStyleName;
 export type AvatarProps = AvatarPrimitive.RootProps & {
     /** The URL of the avatar image. If null or undefined, a generated avatar will be used. */
     src?: string | null;
@@ -13,6 +17,20 @@ export type AvatarProps = AvatarPrimitive.RootProps & {
     seed?: string;
     /** The Dicebear style used for the generated fallback avatar. @default 'shapes' */
     dicebearStyle?: DicebearStyle;
+    /**
+     * Hex background colors (no `#`) for the generated fallback avatar. Defaults to the
+     * current app's own M3 container-tier tokens (`getMaterialAvatarPalette()`), read live
+     * from CSS custom properties — every app's tokens differ since they derive from that
+     * app's own chosen source color, so the fallback isn't a fixed palette.
+     */
+    backgroundColor?: string[];
+    /**
+     * DiceBear variant tags for the generated fallback avatar, e.g. `['animation']` to opt a
+     * supporting style (`gaze`, `shapes`, `blobs`, …) into its animated variants, or
+     * `['!animation']` to force the static one. A no-op for styles without that tag.
+     * @see https://www.dicebear.com/guides/filter-variants-with-tags
+     */
+    tags?: string[];
     /** The loading status of the avatar image. */
     loadingStatus?: 'loading' | 'loaded' | 'error';
     /** Callback for when the avatar is clicked. If provided, the avatar is wrapped in a button. */