@stridge/noctis 1.0.0-beta.0

package/dist/components/avatar/avatar.d.ts

@@ -0,0 +1,235 @@
+import { AvatarIndicatorPlacement, AvatarIndicatorPreset, AvatarShape, AvatarSize, AvatarSpacing } from "./avatar.types.js";
+import { AvatarFallbackPropsArgs, AvatarGroupPropsArgs, AvatarIndicatorPropsArgs, AvatarPartProps, AvatarRootPropsArgs, fallbackProps, groupOverflowProps, groupProps, imageProps, indicatorProps, rootProps } from "./avatar.props.js";
+import { avatar_d_exports } from "../../primitives/avatar.js";
+import * as _$react from "react";
+import { ReactElement } from "react";
+
+//#region src/components/avatar/avatar.d.ts
+/**
+ * Owns the box footprint and shape, sharing them with the strip via the rendered `data-size`/`data-shape`
+ * the `avatar.css` keys its metrics off, and inheriting both from an enclosing `Avatar.Group`. Compose
+ * `Avatar.Image` (the photo) with `Avatar.Fallback` (initials or a glyph), which Base UI shows whenever
+ * the image is absent or fails to load; add an `Avatar.Indicator` for a presence/status dot.
+ *
+ * a11y is two-mode: by default the avatar is **decorative** (no role; pair it with a visible name and
+ * give `Avatar.Image` an empty `alt`). Pass `aria-label` to make it **informative** — a standalone
+ * avatar then announces itself once as an image (`role="img"`).
+ */
+declare function AvatarRoot({
+  size,
+  shape,
+  disabled,
+  ring,
+  role,
+  "aria-label": ariaLabel,
+  className,
+  children,
+  ...props
+}: Avatar.Root.Props): ReactElement;
+/**
+ * The profile image. Crops to cover the box and follows its shape; Base UI swaps it out for the
+ * `Avatar.Fallback` when `src` is missing or the load errors, and cross-fades it in on load. Keep `alt`
+ * empty (`""`) in the decorative case — the surrounding name is the accessible label.
+ */
+declare function AvatarImage({
+  onLoadingStatusChange,
+  className,
+  ...props
+}: Avatar.Image.Props): ReactElement;
+/**
+ * Shown when no image loads — initials or a glyph on a static, accent-independent swatch. Pass `seed`
+ * (a user id, name, or email) to hash a stable `bg-avatar-N` colour, so the same person always gets the
+ * same hue; omit it for the neutral muted fill. Base UI handles the `delay` before it appears.
+ */
+declare function AvatarFallback({
+  seed,
+  className,
+  children,
+  ...props
+}: Avatar.Fallback.Props): ReactElement;
+/**
+ * A corner presence/status dot. The `preset` picks both the fill — a `--noctis-color-presence-*` role
+ * (online/busy/focus/away/offline) or a status role (approved/declined/locked) — and a default
+ * localized screen-reader label, so the dot is never a colour-only signal. Override the announced text
+ * with `aria-label`. Carries a canvas-coloured ring so it reads against the photo.
+ */
+declare function AvatarIndicator({
+  preset,
+  placement,
+  "aria-label": ariaLabel,
+  className,
+  children,
+  ...props
+}: Avatar.Indicator.Props): ReactElement;
+/**
+ * An opt-in loading placeholder shown only while an `Avatar.Image` is actively loading — distinct from
+ * the permanent `Avatar.Fallback` (shown on error or when there's no image). A muted fill that pulses
+ * gently, falling back to a static fill under reduced motion. Renders nothing once the image has loaded.
+ */
+declare function AvatarSkeleton({
+  className,
+  ...props
+}: Avatar.Skeleton.Props): ReactElement | null;
+/**
+ * A facepile — a row of avatars overlapped with a canvas-coloured separating ring so each reads against
+ * the next. Set `size`/`shape` on the group and every child inherits them (an explicit prop on a child
+ * still wins). Beyond `max` avatars, the rest collapse into a non-interactive `+N` overflow chip.
+ */
+declare function AvatarGroup({
+  max,
+  size,
+  shape,
+  spacing,
+  role,
+  className,
+  children,
+  ...props
+}: Avatar.Group.Props): ReactElement;
+/**
+ * The `+N` overflow chip an `Avatar.Group` renders for the members past `max`. A non-interactive,
+ * avatar-shaped count (so it overlaps and rings like the rest of the stack) — Avatar represents avatars,
+ * not controls, so it is plain markup, not a button. The visible `+N` is decorative; a visually-hidden
+ * "N more members" carries the count to assistive tech. To make the overflow actionable (reveal the
+ * hidden members), a consumer wraps the group/chip in their own trigger.
+ */
+declare function AvatarGroupOverflow({
+  count,
+  size,
+  shape,
+  "aria-label": label,
+  className,
+  children,
+  ...props
+}: Avatar.GroupOverflow.Props): ReactElement;
+/**
+ * A user's profile picture, with a graceful fallback. `Avatar.Root` sets the footprint (`size`) and
+ * `shape` (a round `circle` or a rounded-corner box); `Avatar.Image` loads the photo and crops it to
+ * the box; `Avatar.Fallback` shows initials or a glyph on a stable, accent-independent swatch when no
+ * image loads. Built on Base UI's Avatar, so the image→fallback swap happens automatically on a load
+ * error, with no layout shift, and the image cross-fades in.
+ *
+ * Compose from parts: `Avatar.Root` owns the box, `Avatar.Image` the photo, `Avatar.Fallback` the
+ * initials behind it, `Avatar.Indicator` a presence/status dot, and `Avatar.Skeleton` a loading
+ * placeholder. Stack many with `Avatar.Group` (which renders an `Avatar.GroupOverflow` `+N` chip past
+ * its `max`).
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+ * exposed through the matching `Avatar` namespace — e.g. `Avatar.Fallback.Props`.
+ */
+declare const Avatar: {
+  /** Owns the footprint + shape. `Avatar.Root.props({ size, shape, ring, disabled })` → its spreadable prop bag. */Root: typeof AvatarRoot & {
+    props: typeof rootProps;
+  }; /** The profile image. `Avatar.Image.props()` → its spreadable prop bag. */
+  Image: typeof AvatarImage & {
+    props: typeof imageProps;
+  }; /** The fallback. `Avatar.Fallback.props({ seed })` → its spreadable prop bag for a foreign element. */
+  Fallback: typeof AvatarFallback & {
+    props: typeof fallbackProps;
+  }; /** The presence/status corner dot. `Avatar.Indicator.props({ preset, placement })` → its prop bag. */
+  Indicator: typeof AvatarIndicator & {
+    props: typeof indicatorProps;
+  }; /** The opt-in loading placeholder, shown only while an image loads. */
+  Skeleton: typeof AvatarSkeleton; /** A facepile of overlapped avatars. `Avatar.Group.props({ spacing })` → its prop bag. */
+  Group: typeof AvatarGroup & {
+    props: typeof groupProps;
+  }; /** The `+N` overflow chip. `Avatar.GroupOverflow.props({ size, shape })` → its prop bag. */
+  GroupOverflow: typeof AvatarGroupOverflow & {
+    props: typeof groupOverflowProps;
+  };
+};
+/**
+ * Per-part prop and state types, mirroring Base UI's `Component.Part.Props` convention. Types-only — it
+ * emits no runtime code and merges with the `Avatar` object above, so `Avatar.Fallback` is the component
+ * value while `Avatar.Fallback.Props` is its prop type.
+ */
+declare namespace Avatar {
+  /** Footprint scale — `2xs` … `xl`. */
+  type Size = AvatarSize;
+  /** Shape — `circle` or `rounded`. */
+  type Shape = AvatarShape;
+  /** The spreadable data-attribute prop bag every `Avatar.*.props()` returns (D12). */
+  type PartProps = AvatarPartProps;
+  namespace Root {
+    type Props = avatar_d_exports.Avatar.Root.Props & {
+      /**
+       * Footprint scale — height and width. Inherited from an enclosing `Avatar.Group` when unset.
+       * @default "md"
+       */
+      size?: AvatarSize;
+      /**
+       * Shape — a round `circle` or a rounded-corner box. Inherited from an `Avatar.Group` when unset.
+       * @default "circle"
+       */
+      shape?: AvatarShape;
+      /**
+       * Dim the avatar and gate its interactive states — an inactive or deactivated user.
+       * @default false
+       */
+      disabled?: boolean;
+      /**
+       * Draw a hairline ring separating the avatar from a same-toned surface.
+       * @default false
+       */
+      ring?: boolean;
+    };
+    type State = avatar_d_exports.Avatar.Root.State;
+    /** Argument to the `Avatar.Root.props(...)` escape-hatch helper. */
+    type PropsArgs = AvatarRootPropsArgs;
+  }
+  namespace Image {
+    type Props = avatar_d_exports.Avatar.Image.Props;
+    type State = avatar_d_exports.Avatar.Image.State;
+  }
+  namespace Fallback {
+    type Props = avatar_d_exports.Avatar.Fallback.Props & {
+      /** A stable identifier hashed to one of ten `bg-avatar-N` swatches; omit for the neutral muted fill. */seed?: string;
+    };
+    type State = avatar_d_exports.Avatar.Fallback.State;
+    /** Argument to the `Avatar.Fallback.props(...)` escape-hatch helper. */
+    type PropsArgs = AvatarFallbackPropsArgs;
+  }
+  namespace Indicator {
+    type Props = Omit<_$react.ComponentPropsWithoutRef<"span">, "color"> & {
+      /** The presence (online/busy/focus/away/offline) or status (approved/declined/locked) preset. */preset: AvatarIndicatorPreset;
+      /**
+       * Which logical corner the dot sits in.
+       * @default "bottom"
+       */
+      placement?: AvatarIndicatorPlacement;
+    };
+    /** Argument to the `Avatar.Indicator.props(...)` escape-hatch helper. */
+    type PropsArgs = AvatarIndicatorPropsArgs;
+  }
+  namespace Skeleton {
+    type Props = _$react.ComponentPropsWithoutRef<"span">;
+  }
+  namespace Group {
+    type Props = Omit<_$react.ComponentPropsWithoutRef<"div">, "color"> & {
+      /**
+       * The maximum number of avatars shown before the rest collapse into a `+N` overflow chip.
+       * @default 5
+       */
+      max?: number; /** Footprint scale shared with every child avatar that doesn't set its own. */
+      size?: AvatarSize; /** Shape shared with every child avatar that doesn't set its own. */
+      shape?: AvatarShape;
+      /**
+       * How tightly the avatars overlap.
+       * @default "cozy"
+       */
+      spacing?: AvatarSpacing;
+    };
+    /** Argument to the `Avatar.Group.props(...)` escape-hatch helper. */
+    type PropsArgs = AvatarGroupPropsArgs;
+  }
+  namespace GroupOverflow {
+    type Props = _$react.ComponentPropsWithoutRef<"span"> & {
+      /** The number of hidden members — rendered as `+{count}`. Supplied by `Avatar.Group`. */count: number; /** Footprint scale; inherited from the group when unset. */
+      size?: AvatarSize; /** Shape; inherited from the group when unset. */
+      shape?: AvatarShape;
+    };
+    /** Argument to the `Avatar.GroupOverflow.props(...)` escape-hatch helper. */
+    type PropsArgs = AvatarRootPropsArgs;
+  }
+}
+//#endregion
+export { Avatar };

package/dist/components/avatar/avatar.js

@@ -0,0 +1,208 @@
+"use client";
+import { useNoctisStringFormatter } from "../../core/use-injected-labels.js";
+import { VisuallyHidden } from "../../core/visually-hidden/visually-hidden.js";
+import { avatar_exports } from "../../primitives/avatar.js";
+import { AvatarGroupProvider, AvatarImageStatusProvider, useAvatarGroup, useAvatarImageStatus } from "./avatar.context.js";
+import { AVATAR_SLOTS } from "./avatar.slots.js";
+import { fallbackProps, groupOverflowProps, groupProps, imageProps, indicatorProps, rootProps } from "./avatar.props.js";
+import { Children, isValidElement, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { avatarIndex } from "@stridge/noctis-design-tokens";
+//#region src/components/avatar/avatar.tsx
+/** The presence presets, separated from status so the indicator picks the right localized SR key + role. */
+const PRESENCE_PRESETS = new Set([
+	"online",
+	"busy",
+	"focus",
+	"away",
+	"offline"
+]);
+/**
+* Owns the box footprint and shape, sharing them with the strip via the rendered `data-size`/`data-shape`
+* the `avatar.css` keys its metrics off, and inheriting both from an enclosing `Avatar.Group`. Compose
+* `Avatar.Image` (the photo) with `Avatar.Fallback` (initials or a glyph), which Base UI shows whenever
+* the image is absent or fails to load; add an `Avatar.Indicator` for a presence/status dot.
+*
+* a11y is two-mode: by default the avatar is **decorative** (no role; pair it with a visible name and
+* give `Avatar.Image` an empty `alt`). Pass `aria-label` to make it **informative** — a standalone
+* avatar then announces itself once as an image (`role="img"`).
+*/
+function AvatarRoot({ size, shape, disabled, ring, role, "aria-label": ariaLabel, className, children, ...props }) {
+	const group = useAvatarGroup();
+	const resolvedSize = size ?? group?.size ?? "md";
+	const resolvedShape = shape ?? group?.shape ?? "circle";
+	const [status, setStatus] = useState("idle");
+	const statusValue = useMemo(() => ({
+		status,
+		setStatus
+	}), [status]);
+	return /* @__PURE__ */ jsx(avatar_exports.Avatar.Root, {
+		"data-slot": AVATAR_SLOTS.root,
+		"data-size": resolvedSize,
+		"data-shape": resolvedShape,
+		"data-disabled": disabled ? "" : void 0,
+		"data-ring": ring ? "" : void 0,
+		role: role ?? (ariaLabel ? "img" : void 0),
+		"aria-label": ariaLabel,
+		className,
+		...props,
+		children: /* @__PURE__ */ jsx(AvatarImageStatusProvider, {
+			value: statusValue,
+			children
+		})
+	});
+}
+/**
+* The profile image. Crops to cover the box and follows its shape; Base UI swaps it out for the
+* `Avatar.Fallback` when `src` is missing or the load errors, and cross-fades it in on load. Keep `alt`
+* empty (`""`) in the decorative case — the surrounding name is the accessible label.
+*/
+function AvatarImage({ onLoadingStatusChange, className, ...props }) {
+	const imageStatus = useAvatarImageStatus();
+	const handleLoadingStatusChange = (next) => {
+		imageStatus?.setStatus(next);
+		onLoadingStatusChange?.(next);
+	};
+	return /* @__PURE__ */ jsx(avatar_exports.Avatar.Image, {
+		"data-slot": AVATAR_SLOTS.image,
+		onLoadingStatusChange: handleLoadingStatusChange,
+		className,
+		...props
+	});
+}
+/**
+* Shown when no image loads — initials or a glyph on a static, accent-independent swatch. Pass `seed`
+* (a user id, name, or email) to hash a stable `bg-avatar-N` colour, so the same person always gets the
+* same hue; omit it for the neutral muted fill. Base UI handles the `delay` before it appears.
+*/
+function AvatarFallback({ seed, className, children, ...props }) {
+	const dataIndex = seed === void 0 ? void 0 : String(avatarIndex(seed));
+	return /* @__PURE__ */ jsx(avatar_exports.Avatar.Fallback, {
+		"data-slot": AVATAR_SLOTS.fallback,
+		"data-avatar-index": dataIndex,
+		className,
+		...props,
+		children
+	});
+}
+/**
+* A corner presence/status dot. The `preset` picks both the fill — a `--noctis-color-presence-*` role
+* (online/busy/focus/away/offline) or a status role (approved/declined/locked) — and a default
+* localized screen-reader label, so the dot is never a colour-only signal. Override the announced text
+* with `aria-label`. Carries a canvas-coloured ring so it reads against the photo.
+*/
+function AvatarIndicator({ preset, placement = "bottom", "aria-label": ariaLabel, className, children, ...props }) {
+	const formatter = useNoctisStringFormatter();
+	const family = PRESENCE_PRESETS.has(preset) ? "presence" : "status";
+	const label = ariaLabel ?? formatter.format(`avatar.${family}.${preset}`);
+	return /* @__PURE__ */ jsxs("span", {
+		"data-slot": AVATAR_SLOTS.indicator,
+		"data-preset": preset,
+		"data-placement": placement,
+		className,
+		...props,
+		children: [/* @__PURE__ */ jsx(VisuallyHidden, { children: label }), children]
+	});
+}
+/**
+* An opt-in loading placeholder shown only while an `Avatar.Image` is actively loading — distinct from
+* the permanent `Avatar.Fallback` (shown on error or when there's no image). A muted fill that pulses
+* gently, falling back to a static fill under reduced motion. Renders nothing once the image has loaded.
+*/
+function AvatarSkeleton({ className, ...props }) {
+	if (useAvatarImageStatus()?.status !== "loading") return null;
+	return /* @__PURE__ */ jsx("span", {
+		"data-slot": AVATAR_SLOTS.skeleton,
+		"aria-hidden": true,
+		className,
+		...props
+	});
+}
+/**
+* A facepile — a row of avatars overlapped with a canvas-coloured separating ring so each reads against
+* the next. Set `size`/`shape` on the group and every child inherits them (an explicit prop on a child
+* still wins). Beyond `max` avatars, the rest collapse into a non-interactive `+N` overflow chip.
+*/
+function AvatarGroup({ max = 5, size, shape, spacing = "cozy", role = "group", className, children, ...props }) {
+	const items = Children.toArray(children).filter(isValidElement);
+	const visible = items.slice(0, max);
+	const overflow = items.length - visible.length;
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": AVATAR_SLOTS.group,
+		"data-spacing": spacing,
+		role,
+		className,
+		...props,
+		children: /* @__PURE__ */ jsxs(AvatarGroupProvider, {
+			value: {
+				size,
+				shape
+			},
+			children: [visible, overflow > 0 ? /* @__PURE__ */ jsx(AvatarGroupOverflow, {
+				count: overflow,
+				size,
+				shape
+			}) : null]
+		})
+	});
+}
+/**
+* The `+N` overflow chip an `Avatar.Group` renders for the members past `max`. A non-interactive,
+* avatar-shaped count (so it overlaps and rings like the rest of the stack) — Avatar represents avatars,
+* not controls, so it is plain markup, not a button. The visible `+N` is decorative; a visually-hidden
+* "N more members" carries the count to assistive tech. To make the overflow actionable (reveal the
+* hidden members), a consumer wraps the group/chip in their own trigger.
+*/
+function AvatarGroupOverflow({ count, size, shape, "aria-label": label, className, children, ...props }) {
+	const group = useAvatarGroup();
+	const resolvedSize = size ?? group?.size ?? "md";
+	const resolvedShape = shape ?? group?.shape ?? "circle";
+	const formatter = useNoctisStringFormatter();
+	const announced = label ?? formatter.format("avatar.overflowLabel", { count });
+	return /* @__PURE__ */ jsxs("span", {
+		"data-slot": AVATAR_SLOTS.root,
+		"data-size": resolvedSize,
+		"data-shape": resolvedShape,
+		"data-avatar-overflow": "",
+		className,
+		...props,
+		children: [/* @__PURE__ */ jsx("span", {
+			"data-slot": AVATAR_SLOTS.fallback,
+			"aria-hidden": true,
+			children: children ?? `+${count}`
+		}), /* @__PURE__ */ jsx(VisuallyHidden, { children: announced })]
+	});
+}
+/**
+* A user's profile picture, with a graceful fallback. `Avatar.Root` sets the footprint (`size`) and
+* `shape` (a round `circle` or a rounded-corner box); `Avatar.Image` loads the photo and crops it to
+* the box; `Avatar.Fallback` shows initials or a glyph on a stable, accent-independent swatch when no
+* image loads. Built on Base UI's Avatar, so the image→fallback swap happens automatically on a load
+* error, with no layout shift, and the image cross-fades in.
+*
+* Compose from parts: `Avatar.Root` owns the box, `Avatar.Image` the photo, `Avatar.Fallback` the
+* initials behind it, `Avatar.Indicator` a presence/status dot, and `Avatar.Skeleton` a loading
+* placeholder. Stack many with `Avatar.Group` (which renders an `Avatar.GroupOverflow` `+N` chip past
+* its `max`).
+*
+* The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+* exposed through the matching `Avatar` namespace — e.g. `Avatar.Fallback.Props`.
+*/
+const Avatar = {
+	/** Owns the footprint + shape. `Avatar.Root.props({ size, shape, ring, disabled })` → its spreadable prop bag. */
+	Root: Object.assign(AvatarRoot, { props: rootProps }),
+	/** The profile image. `Avatar.Image.props()` → its spreadable prop bag. */
+	Image: Object.assign(AvatarImage, { props: imageProps }),
+	/** The fallback. `Avatar.Fallback.props({ seed })` → its spreadable prop bag for a foreign element. */
+	Fallback: Object.assign(AvatarFallback, { props: fallbackProps }),
+	/** The presence/status corner dot. `Avatar.Indicator.props({ preset, placement })` → its prop bag. */
+	Indicator: Object.assign(AvatarIndicator, { props: indicatorProps }),
+	/** The opt-in loading placeholder, shown only while an image loads. */
+	Skeleton: AvatarSkeleton,
+	/** A facepile of overlapped avatars. `Avatar.Group.props({ spacing })` → its prop bag. */
+	Group: Object.assign(AvatarGroup, { props: groupProps }),
+	/** The `+N` overflow chip. `Avatar.GroupOverflow.props({ size, shape })` → its prop bag. */
+	GroupOverflow: Object.assign(AvatarGroupOverflow, { props: groupOverflowProps })
+};
+//#endregion
+export { Avatar };

package/dist/components/avatar/avatar.props.d.ts

@@ -0,0 +1,86 @@
+import { AvatarIndicatorPlacement, AvatarIndicatorPreset, AvatarShape, AvatarSize, AvatarSpacing } from "./avatar.types.js";
+
+//#region src/components/avatar/avatar.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every `Avatar.*.props()` returns. */
+type AvatarPartProps = {
+  /** The slot value the matching `avatar.css` rules anchor on. */"data-slot": string; /** Forwarded verbatim — styling is attribute-driven, so this is an optional consumer passthrough. */
+  className?: string; /** A data-attribute present (string) or absent (`undefined`); never `false`. */
+  [attr: `data-${string}`]: string | undefined;
+};
+/** Common shape: every part's `.props()` accepts an optional `className` passthrough. */
+interface BasePropsArgs {
+  /** Forwarded verbatim onto the returned prop bag. */
+  className?: string;
+}
+/** Argument to `Avatar.Root.props(...)` — the box's size + shape and its ring/disabled flags. */
+interface AvatarRootPropsArgs extends BasePropsArgs {
+  /** Footprint scale — `2xs` | `xs` | `sm` | `md` | `lg` | `xl`. @default "md" */
+  size?: AvatarSize;
+  /** Shape — `circle` (fully round) or `rounded` (rounded corners). @default "circle" */
+  shape?: AvatarShape;
+  /** Dim the avatar and gate its interactive states — an inactive/deactivated user. @default false */
+  disabled?: boolean;
+  /** Draw a hairline ring separating the avatar from a same-toned surface. @default false */
+  ring?: boolean;
+}
+/** Argument to a stateless part's `.props(...)` — no recipe of its own; metrics flow from the root. */
+type AvatarStatelessPropsArgs = BasePropsArgs;
+/** Argument to `Avatar.Fallback.props(...)` — the seed that selects the static swatch the fill reads. */
+interface AvatarFallbackPropsArgs extends BasePropsArgs {
+  /**
+   * A stable identifier (a user id, name, or email) hashed to one of the ten `bg-avatar-N` swatches,
+   * so the same person always lands on the same colour. Omit to fall back to the neutral muted fill.
+   */
+  seed?: string;
+}
+/** Argument to `Avatar.Indicator.props(...)` — the corner presence/status dot's preset and placement. */
+interface AvatarIndicatorPropsArgs extends BasePropsArgs {
+  /** The presence (online/busy/focus/away/offline) or status (approved/declined/locked) preset. */
+  preset: AvatarIndicatorPreset;
+  /** Which logical corner the dot sits in. @default "bottom" */
+  placement?: AvatarIndicatorPlacement;
+}
+/** Argument to `Avatar.Group.props(...)` — the overlapped row's spacing tightness. */
+interface AvatarGroupPropsArgs extends BasePropsArgs {
+  /** How tightly the avatars overlap. @default "cozy" */
+  spacing?: AvatarSpacing;
+}
+/** Root prop bag: `data-slot` plus the `data-size`/`data-shape` the descendant rules read, and the flags. */
+declare function rootProps({
+  size,
+  shape,
+  disabled,
+  ring,
+  className
+}?: AvatarRootPropsArgs): AvatarPartProps;
+/** Image prop bag: just the slot anchor (the box metrics flow from the root). */
+declare function imageProps({
+  className
+}?: AvatarStatelessPropsArgs): AvatarPartProps;
+/** Fallback prop bag: the slot anchor plus the hashed `data-avatar-index` that selects the swatch fill. */
+declare function fallbackProps({
+  seed,
+  className
+}?: AvatarFallbackPropsArgs): AvatarPartProps;
+/** Indicator prop bag: the slot anchor plus the `data-preset`/`data-placement` the dot reads its fill + corner off. */
+declare function indicatorProps({
+  preset,
+  placement,
+  className
+}: AvatarIndicatorPropsArgs): AvatarPartProps;
+/** Group prop bag: the slot anchor plus the `data-spacing` the overlap rules key off. */
+declare function groupProps({
+  spacing,
+  className
+}?: AvatarGroupPropsArgs): AvatarPartProps;
+/**
+ * Overflow-chip prop bag: the `+N` chip reuses the `noctis-avatar` slot (so it inherits the box,
+ * overlap, and separating ring) marked with `data-avatar-overflow`. Spread onto the non-interactive chip.
+ */
+declare function groupOverflowProps({
+  size,
+  shape,
+  className
+}?: AvatarRootPropsArgs): AvatarPartProps;
+//#endregion
+export { AvatarFallbackPropsArgs, AvatarGroupPropsArgs, AvatarIndicatorPropsArgs, AvatarPartProps, AvatarRootPropsArgs, fallbackProps, groupOverflowProps, groupProps, imageProps, indicatorProps, rootProps };

package/dist/components/avatar/avatar.props.js

@@ -0,0 +1,78 @@
+import { AVATAR_SLOTS } from "./avatar.slots.js";
+import { avatarIndex } from "@stridge/noctis-design-tokens";
+//#region src/components/avatar/avatar.props.ts
+/**
+* The D12 unified variant contract for Avatar — the data-attribute-native styling helpers.
+*
+* Each compound part exposes a `props(...)` builder returning a **spreadable props object** of the form
+* `{ "data-slot": "noctis-avatar-<part>", ...dataAttrs }`, derived from the part's size/shape/seed
+* inputs. Under the single-`data-slot` anchor model the `data-slot` is the only styling hook needed —
+* `avatar.css` keys every rule off it plus the `data-*` recipe — so spreading a part's `props()` onto a
+* *foreign* element styles it as that part:
+*
+*     <span {...Avatar.Root.props({ size: "lg" })}>
+*       <img {...Avatar.Image.props()} src="…" alt="Ada" />
+*     </span>
+*     // → <span data-slot="noctis-avatar" data-size="lg" data-shape="circle">
+*
+* The escape hatch carries no className (styling is attribute-driven); an optional `className`
+* passthrough is accepted and forwarded verbatim. The same variant→data-attribute→values mapping is
+* emitted as data from the token graph (`generated/declarations.json` → `variantSchema`) so non-React /
+* agent consumers can hand-write the markup from the docs.
+*/
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** A boolean flag → a present (empty-string) or absent data-attribute; never `false`. */
+const flag = (on) => on ? "" : void 0;
+/** Root prop bag: `data-slot` plus the `data-size`/`data-shape` the descendant rules read, and the flags. */
+function rootProps({ size = "md", shape = "circle", disabled, ring, className } = {}) {
+	return withClassName({
+		"data-slot": AVATAR_SLOTS.root,
+		"data-size": size,
+		"data-shape": shape,
+		"data-disabled": flag(disabled),
+		"data-ring": flag(ring)
+	}, className);
+}
+/** Image prop bag: just the slot anchor (the box metrics flow from the root). */
+function imageProps({ className } = {}) {
+	return withClassName({ "data-slot": AVATAR_SLOTS.image }, className);
+}
+/** Fallback prop bag: the slot anchor plus the hashed `data-avatar-index` that selects the swatch fill. */
+function fallbackProps({ seed, className } = {}) {
+	return withClassName({
+		"data-slot": AVATAR_SLOTS.fallback,
+		"data-avatar-index": seed === void 0 ? void 0 : String(avatarIndex(seed))
+	}, className);
+}
+/** Indicator prop bag: the slot anchor plus the `data-preset`/`data-placement` the dot reads its fill + corner off. */
+function indicatorProps({ preset, placement = "bottom", className }) {
+	return withClassName({
+		"data-slot": AVATAR_SLOTS.indicator,
+		"data-preset": preset,
+		"data-placement": placement
+	}, className);
+}
+/** Group prop bag: the slot anchor plus the `data-spacing` the overlap rules key off. */
+function groupProps({ spacing = "cozy", className } = {}) {
+	return withClassName({
+		"data-slot": AVATAR_SLOTS.group,
+		"data-spacing": spacing
+	}, className);
+}
+/**
+* Overflow-chip prop bag: the `+N` chip reuses the `noctis-avatar` slot (so it inherits the box,
+* overlap, and separating ring) marked with `data-avatar-overflow`. Spread onto the non-interactive chip.
+*/
+function groupOverflowProps({ size = "md", shape = "circle", className } = {}) {
+	return withClassName({
+		"data-slot": AVATAR_SLOTS.root,
+		"data-size": size,
+		"data-shape": shape,
+		"data-avatar-overflow": ""
+	}, className);
+}
+//#endregion
+export { fallbackProps, groupOverflowProps, groupProps, imageProps, indicatorProps, rootProps };

package/dist/components/avatar/avatar.slots.d.ts

@@ -0,0 +1,35 @@
+//#region src/components/avatar/avatar.slots.d.ts
+/**
+ * The `data-*` hooks `Avatar` stamps on its parts, for host-side styling and tests. Slot values mark
+ * each rendered element; the `data-size`/`data-shape` axes carry the recipe the precompiled
+ * `avatar.css` keys its box metrics off, and `data-avatar-index` selects which static fallback swatch
+ * paints. The group lays out an overlapped row (`data-spacing`); its `+N` overflow chip is a
+ * non-interactive avatar-shaped count marked with `data-avatar-overflow` (it reuses the `noctis-avatar`
+ * slot so it inherits the box/overlap/ring). Base UI's Avatar drives the
+ * image-loading status the fallback shows behind, plus the `data-starting-style` enter transition the
+ * image cross-fades on.
+ */
+declare enum AvatarDataAttributes {
+  /** The root avatar element. */
+  slot = "data-slot",
+  /** The size scale — `2xs` | `xs` | `sm` | `md` | `lg` | `xl`; the generated layer keys the per-size internals off it. */
+  size = "data-size",
+  /** The shape — `circle` (default, fully round) | `rounded` (rounded corners). */
+  shape = "data-shape",
+  /** `1`–`10`, the stable hashed swatch index the fallback fill reads its `bg-avatar-N` role from. */
+  avatarIndex = "data-avatar-index",
+  /** Present when the avatar is dimmed/inactive — gates interactive states and applies the disabled opacity. */
+  disabled = "data-disabled",
+  /** Present when the avatar carries a hairline ring separating it from its surface. */
+  ring = "data-ring",
+  /** The indicator preset — a presence or status value; the dot reads its fill role from it. */
+  preset = "data-preset",
+  /** The indicator's logical corner — `top` | `bottom` (default). */
+  placement = "data-placement",
+  /** The group's overlap tightness — `tight` | `cozy` (default). */
+  spacing = "data-spacing",
+  /** Marks the group's `+N` overflow chip (a non-interactive avatar-shaped count). */
+  overflow = "data-avatar-overflow"
+}
+//#endregion
+export { AvatarDataAttributes };