@astryxdesign/core 0.2.0-canary.85f5022 → 0.2.0-canary.8dfd7cf

package/locales/en.json

@@ -247,6 +247,10 @@
     "defaultMessage": "Use arrow keys to move between avatars",
     "description": "Screen-reader-only instruction attached (via aria-describedby) to a group of interactive avatars that share a single Tab stop. Tells keyboard users the Left/Right arrow keys move focus between the avatars. Only announced when the group has interactive (link/button) avatars."
   },
+  "@astryx.avatarGroup.overflow": {
+    "defaultMessage": "{count, number} more",
+    "description": "Accessible name for the \"+N\" overflow indicator at the end of an AvatarGroup — announces how many additional avatars are not shown. Example: `5 more`. The visible \"+N\" text is unaffected; this is the aria-label only."
+  },
   "@astryx.banner.dismiss": {
     "defaultMessage": "Dismiss",
     "description": "\"Dismiss\" = close/hide this notification (not \"reject a person\"). Aria label AND tooltip on the small X button on a Banner."
@@ -407,6 +411,10 @@
     "defaultMessage": "Search options",
     "description": "Screen-reader-only accessible name for that same search input inside a MultiSelector."
   },
+  "@astryx.multiSelector.selectAllPartiallySelected": {
+    "defaultMessage": "{label}, partially selected",
+    "description": "Accessible name for the MultiSelector select-all option while only some options are selected. `{label}` is the visible select-all label (e.g. \"Select all\"). ARIA forbids aria-selected=\"mixed\" on options, so the indeterminate state is conveyed through the name instead. \"Partially\" = some but not all."
+  },
   "@astryx.popover.close": {
     "defaultMessage": "Close popover",
     "description": "\"Close\" = shut/dismiss, not \"nearby\". Screen-reader-only label on the close button inside a Popover."
@@ -683,6 +691,10 @@
     "defaultMessage": "Expand",
     "description": "\"Expand\" = reveal more, not grow physically. Aria label AND tooltip on the same toggle when currently collapsed. Pairs with `banner.collapse`."
   },
+  "@astryx.button.loading": {
+    "defaultMessage": "Loading",
+    "description": "Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense (\"work in progress\"), not a noun. Kept separate from `typeahead.loading` — translations may diverge."
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is collapsed. `{label}` is the drawer's visible name — example: `Expand Attachments`. Pairs with `collapse`."
@@ -747,6 +759,14 @@
     "defaultMessage": "Code",
     "description": "Screen-reader-only fallback name for a code-snippet scroll container when the code's language is unknown. \"Code\" = source code, not secret code or code of conduct."
   },
+  "@astryx.field.optional": {
+    "defaultMessage": "Optional",
+    "description": "Visible indicator shown next to a form field's label when the field is optional (isOptional). Mutually exclusive with the required indicator. Very short — appears inline after the label text."
+  },
+  "@astryx.field.required": {
+    "defaultMessage": "Required",
+    "description": "Visible indicator shown next to a form field's label when the field must be filled in (isRequired). Mutually exclusive with the optional indicator. Very short — appears inline after the label text."
+  },
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that removes the selected file from a FileInput. Example: `Clear Attachment`, `Clear Résumé`."
@@ -759,10 +779,22 @@
     "defaultMessage": "{label}, {fileNames}",
     "description": "Accessible name for a FileInput trigger that has files attached, composing the field label with the selected filenames. Example: `Attachments, report.pdf, notes.txt`."
   },
+  "@astryx.keyboardHint.toNavigate": {
+    "defaultMessage": "to navigate",
+    "description": "Trailing text in the keyboard-hint badge, shown after arrow-key icons — reads as `← → to navigate`. Lowercase sentence fragment completing the visual phrase; the badge is aria-hidden, so this is for sighted users only."
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "Media viewer",
     "description": "Screen-reader-only fallback name for the Lightbox dialog when the current media item has no alt text. Should rarely render — consumers should provide alt."
   },
+  "@astryx.metadataList.showMore": {
+    "defaultMessage": "Show more",
+    "description": "Button label under a MetadataList that reveals items hidden beyond the configured maximum. Toggles with `metadataList.showLess` — keep the pair parallel in your language."
+  },
+  "@astryx.metadataList.showLess": {
+    "defaultMessage": "Show less",
+    "description": "Button label under a MetadataList that re-hides the extra items revealed by `metadataList.showMore`. Keep the pair parallel."
+  },
   "@astryx.mobileNav.navigation": {
     "defaultMessage": "Navigation",
     "description": "Screen-reader-only fallback name for the MobileNav overlay dialog when no explicit label was passed."
@@ -851,6 +883,14 @@
     "defaultMessage": "Expand all rows",
     "description": "Aria label for the Table tree-data header toggle when rows are collapsed and clicking it expands them."
   },
+  "@astryx.textArea.charactersRemaining": {
+    "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} remaining",
+    "description": "Screen-reader-only announcement of how many characters the user can still type before hitting a TextArea's maxLength. Announced politely as the count nears the limit. `{count}` is the number remaining — example: `12 characters remaining`."
+  },
+  "@astryx.textArea.charactersOverLimit": {
+    "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} over the limit",
+    "description": "Screen-reader-only assertive announcement when the user has typed past a TextArea's maxLength. `{count}` is how many characters over — example: `3 characters over the limit`."
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a TextInput. Example: `Clear Email`, `Clear Name`."

package/locales/pseudo.json

@@ -185,6 +185,9 @@
   "@astryx.avatarGroup.keyboardHint": {
     "defaultMessage": "⟦Úšé àřřóŵ ķéýš ţó ɱóṽé ƀéţŵééñ àṽàţàřš⟧"
   },
+  "@astryx.avatarGroup.overflow": {
+    "defaultMessage": "⟦{count, number} ɱóřé⟧"
+  },
   "@astryx.banner.dismiss": {
     "defaultMessage": "⟦Ðíšɱíšš⟧"
   },
@@ -305,6 +308,9 @@
   "@astryx.multiSelector.searchOptions": {
     "defaultMessage": "⟦Šéàřçĥ óþţíóñš⟧"
   },
+  "@astryx.multiSelector.selectAllPartiallySelected": {
+    "defaultMessage": "⟦{label}, þàřţíàłłý šéłéçţéð⟧"
+  },
   "@astryx.popover.close": {
     "defaultMessage": "⟦Çłóšé þóþóṽéř⟧"
   },
@@ -512,6 +518,9 @@
   "@astryx.banner.expand": {
     "defaultMessage": "⟦Éẋþàñð⟧"
   },
+  "@astryx.button.loading": {
+    "defaultMessage": "⟦Łóàðíñĝ⟧"
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "⟦Éẋþàñð {label}⟧"
   },
@@ -560,6 +569,12 @@
   "@astryx.codeBlock.code": {
     "defaultMessage": "⟦Çóðé⟧"
   },
+  "@astryx.field.optional": {
+    "defaultMessage": "⟦Óþţíóñàł⟧"
+  },
+  "@astryx.field.required": {
+    "defaultMessage": "⟦Řéɋúířéð⟧"
+  },
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
@@ -569,9 +584,18 @@
   "@astryx.fileInput.triggerWithFiles": {
     "defaultMessage": "⟦{label}, {fileNames}⟧"
   },
+  "@astryx.keyboardHint.toNavigate": {
+    "defaultMessage": "⟦ţó ñàṽíĝàţé⟧"
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "⟦Ṁéðíà ṽíéŵéř⟧"
   },
+  "@astryx.metadataList.showMore": {
+    "defaultMessage": "⟦Šĥóŵ ɱóřé⟧"
+  },
+  "@astryx.metadataList.showLess": {
+    "defaultMessage": "⟦Šĥóŵ łéšš⟧"
+  },
   "@astryx.mobileNav.navigation": {
     "defaultMessage": "⟦Ñàṽíĝàţíóñ⟧"
   },
@@ -638,6 +662,12 @@
   "@astryx.tableTree.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.textArea.charactersRemaining": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} řéɱàíñíñĝ⟧"
+  },
+  "@astryx.textArea.charactersOverLimit": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} óṽéř ţĥé łíɱíţ⟧"
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.2.0-canary.85f5022",
+  "version": "0.2.0-canary.8dfd7cf",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -64,16 +64,6 @@
       "types": "./dist/naming.d.ts",
       "default": "./dist/naming.js"
     },
-    "./config": {
-      "source": "./src/config.ts",
-      "types": "./dist/config.d.ts",
-      "default": "./dist/config.js"
-    },
-    "./authoring": {
-      "source": "./src/authoring/index.ts",
-      "types": "./dist/authoring/index.d.ts",
-      "default": "./dist/authoring/index.js"
-    },
     "./theme/tokens": {
       "source": "./src/theme/tokens.ts",
       "types": "./dist/theme/tokens.d.ts",
@@ -654,7 +644,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.29.7",
+    "@astryxdesign/cli": "0.2.0-canary.8dfd7cf",
+    "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^7.29.7",
@@ -669,7 +660,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs",
+    "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",
     "build:i18n": "node scripts/build-pseudo-locale.mjs",
     "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",
     "build:css": "node ../../scripts/build-css.mjs",

package/src/AlertDialog/AlertDialog.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AlertDialog',
@@ -30,7 +30,7 @@ export const docs = {
   },
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
-  // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
+  // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
   // in docs-types.ts (#3657).
   playground: {
     defaults: {
@@ -120,7 +120,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
   usage: {

package/src/AlertDialog/AlertDialog.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/AlertDialog/AlertDialog.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/AlertDialog/index.ts (exports if types change)
  * - /apps/storybook/stories/AlertDialog.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/AlertDialog/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AlertDialog/ (showcase blocks)
  */
 
 import React, {useId, useCallback} from 'react';

package/src/AlertDialog/useImperativeAlertDialog.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'useImperativeAlertDialog',

package/src/AppShell/AppShell.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AppShell',
@@ -120,7 +120,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'AppShell',
   displayName: 'App Shell',
@@ -182,7 +182,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'app-level layout shell w/ header, side nav, main content; composes Layout internally, replaces Page+PageLayout',

package/src/AppShell/AppShell.tsx

@@ -17,7 +17,7 @@ import React from 'react';
  * - /packages/core/src/AppShell/index.ts
  * - /packages/core/src/AppShell/AppShell.test.tsx
  * - /apps/storybook/stories/AppShell.stories.tsx
- * - /packages/cli/templates/blocks/components/AppShell/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AppShell/ (showcase blocks)
  */
 
 import {
@@ -55,6 +55,7 @@ import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import type {AppShellVariantMap} from './index';
 
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
@@ -101,25 +102,6 @@ export type AppShellBreakpoint = 'sm' | 'md' | 'lg' | 'none';
  * - `elevated`: Wash nav background with elevated surface content + border radius
  * @default 'elevated'
  */
-/**
- * Extensible variant map for AppShell.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/AppShell' {
- *   interface AppShellVariantMap {
- *     'glass': true;
- *   }
- * }
- * ```
- */
-export interface AppShellVariantMap {
-  wash: true;
-  surface: true;
-  section: true;
-  elevated: true;
-}
 
 /**
  * Navigation background style. Extensible via module augmentation of AppShellVariantMap.

package/src/AppShell/index.ts

@@ -11,12 +11,31 @@
  * SYNC: When modified, update this header and /packages/core/src/AppShell/AppShell.doc.mjs
  */
 
+/**
+ * Extensible variant map for AppShell.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/AppShell' {
+ *   interface AppShellVariantMap {
+ *     'glass': true;
+ *   }
+ * }
+ * ```
+ */
+export interface AppShellVariantMap {
+  wash: true;
+  surface: true;
+  section: true;
+  elevated: true;
+}
+
 export {AppShell} from './AppShell';
 export type {
   AppShellProps,
   AppShellBreakpoint,
   AppShellVariant,
-  AppShellVariantMap,
   MobileNavConfig,
 } from './AppShell';
 export {

package/src/AppShell/useAppShellMobile.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useAppShellMobile',
   displayName: 'useAppShellMobile',
@@ -109,7 +109,7 @@ export const docs = {
   importPath: '@astryxdesign/core/AppShell',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Reads/controls AppShell mobile nav context. Use for custom triggers, closing drawer after route changes, or syncing AppShell-adjacent mobile UI to the same breakpoint as mobile nav.',

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AspectRatio',
@@ -62,7 +62,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'AspectRatio',
   displayName: 'Aspect Ratio',
@@ -105,7 +105,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'maintains specific aspect ratio for children',
   usage: {

package/src/AspectRatio/AspectRatio.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
  * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
  * - /apps/storybook/stories/AspectRatio.stories.tsx
- * - /packages/cli/templates/blocks/components/AspectRatio/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AspectRatio/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/Avatar/Avatar.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Avatar',
@@ -128,7 +128,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -142,7 +142,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'person/team avatar w/ photo → initials → icon fallback chain',
   usage: {

package/src/Avatar/Avatar.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Avatar/index.ts (exports if types change)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Avatar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  *
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
@@ -215,8 +215,13 @@ const dynamicStyles = stylex.create({
   }),
   statusPosition: (size: number) => ({
     bottom: size * CIRCLE_EDGE_OFFSET_RATIO,
-    right: size * CIRCLE_EDGE_OFFSET_RATIO,
-    transform: 'translate(50%, 50%)',
+    insetInlineEnd: size * CIRCLE_EDGE_OFFSET_RATIO,
+    // `insetInlineEnd` anchors to the right edge in LTR / left in RTL, so the
+    // outward push must mirror too: +X in LTR, −X in RTL (Y is unaffected).
+    transform: {
+      default: 'translate(50%, 50%)',
+      ':is([dir="rtl"] *)': 'translate(-50%, 50%)',
+    },
   }),
 });
 

package/src/Avatar/AvatarStatusDot.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AvatarStatusDot',

package/src/Avatar/AvatarStatusDot.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/Avatar/Avatar.doc.mjs (features, files table)
  * - /packages/core/src/Avatar/index.ts (exports)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Avatar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  */
 
 import React, {use, type ReactNode} from 'react';
@@ -22,6 +22,7 @@ import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
 import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import type {AvatarStatusDotVariantMap} from './index';
 
 /**
  * Discrete size tier of the status dot, derived from the avatar size.
@@ -65,32 +66,6 @@ function resolveStatusDotSize(avatarSize: number): {
   return {dotSize: 32, borderWidth: 4, iconSize: 18, tier: 'large'};
 }
 
-/**
- * Extensible variant map for AvatarStatusDot.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Avatar' {
- *   interface AvatarStatusDotVariantMap {
- *     'away': true;
- *   }
- * }
- * ```
- *
- * Custom variants render no background fill, no ink colour, and no built-in
- * shape glyph — the theme must supply the fill and, if it passes an `icon`,
- * a `color` for it to paint with. It should also supply a non-colour mark
- * so the status is not distinguishable by colour alone (a WCAG 1.4.1
- * failure): pass `icon`, or theme a glyph onto the dot via
- * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
- */
-export interface AvatarStatusDotVariantMap {
-  success: true;
-  neutral: true;
-  error: true;
-}
-
 /**
  * AvatarStatusDot variant type. Extensible via module augmentation of AvatarStatusDotVariantMap.
  */

package/src/Avatar/index.ts

@@ -11,11 +11,36 @@
  * SYNC: When modified, update this header and /packages/core/src/Avatar/Avatar.doc.mjs
  */
 
+/**
+ * Extensible variant map for AvatarStatusDot.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Avatar' {
+ *   interface AvatarStatusDotVariantMap {
+ *     'away': true;
+ *   }
+ * }
+ * ```
+ *
+ * Custom variants render no background fill, no ink colour, and no built-in
+ * shape glyph — the theme must supply the fill and, if it passes an `icon`,
+ * a `color` for it to paint with. It should also supply a non-colour mark
+ * so the status is not distinguishable by colour alone (a WCAG 1.4.1
+ * failure): pass `icon`, or theme a glyph onto the dot via
+ * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
+ */
+export interface AvatarStatusDotVariantMap {
+  success: true;
+  neutral: true;
+  error: true;
+}
+
 export {Avatar, resolveSize} from './Avatar';
 export type {AvatarProps, AvatarSize} from './Avatar';
 export {AvatarStatusDot} from './AvatarStatusDot';
 export type {
   AvatarStatusDotProps,
   AvatarStatusDotVariant,
-  AvatarStatusDotVariantMap,
 } from './AvatarStatusDot';

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -1,5 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AvatarGroup',
@@ -71,7 +71,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -85,7 +85,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'compositional overlapping avatar row w/ +N overflow or custom slot',
   usage: {

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -5,6 +5,7 @@ import userEvent from '@testing-library/user-event';
 import {AvatarGroup} from './AvatarGroup';
 import {AvatarGroupOverflow} from './AvatarGroupOverflow';
 import {Avatar, AvatarStatusDot} from '../Avatar';
+import {InternationalizationProvider} from '../i18n';
 
 describe('AvatarGroup', () => {
   it('renders all avatar children', () => {
@@ -238,7 +239,26 @@ describe('AvatarGroupOverflow — hardening', () => {
     );
 
     expect(screen.getByText('+4912')).toBeInTheDocument();
-    expect(screen.getByLabelText('4912 more')).toBeInTheDocument();
+    // The aria-label routes through the catalog's `{count, number}` ICU
+    // argument, so the en locale adds a grouping separator.
+    expect(screen.getByLabelText('4,912 more')).toBeInTheDocument();
+  });
+
+  it('localizes the overflow label through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.avatarGroup.overflow': '{count, number} de plus'},
+        }}>
+        <AvatarGroup>
+          <Avatar name="Alice" />
+          <AvatarGroupOverflow count={3} />
+        </AvatarGroup>
+      </InternationalizationProvider>,
+    );
+
+    expect(screen.getByLabelText('3 de plus')).toBeInTheDocument();
   });
 });
 

package/src/AvatarGroup/AvatarGroup.tsx

@@ -21,7 +21,7 @@
  * - /packages/core/src/AvatarGroup/AvatarGroup.doc.mjs (props table, features)
  * - /packages/core/src/AvatarGroup/index.ts (exports if types change)
  * - /apps/storybook/stories/AvatarGroup.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/AvatarGroup/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AvatarGroup/ (showcase blocks)
  */
 
 import {useId, useMemo, useState, type ReactNode} from 'react';

package/src/AvatarGroup/AvatarGroupOverflow.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AvatarGroupOverflow',