@astryxdesign/core 0.1.8 → 0.1.9-canary.75d2d03

package/src/Avatar/AvatarStatusDot.tsx

@@ -20,37 +20,49 @@ import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 /**
- * Resolves the status dot size, border width, and icon size based on the
- * avatar size.
+ * Discrete size tier of the status dot, derived from the avatar size.
+ * Keys the built-in shape glyph's stroke weight — see `GLYPH_STROKE_WIDTH`.
+ */
+type StatusDotSizeTier = 'small' | 'medium' | 'large';
+
+/**
+ * Resolves the status dot size, border width, icon size, and size tier
+ * based on the avatar size.
  *
  * Uses discrete size tiers rather than a continuous ratio so the dot
  * looks intentional at every avatar size:
  *
- *   | Avatar size  | Dot  | Border | Icon |
- *   |--------------|------|--------|------|
- *   | ≤ 36px       | 10px | 1px    | —    |
- *   | 40–72px      | 20px | 2px    | 12px |
- *   | ≥ 96px       | 32px | 4px    | 18px |
+ *   | Avatar size  | Tier   | Dot  | Border | Icon | Field | Glyph stroke |
+ *   |--------------|--------|------|--------|------|-------|--------------|
+ *   | ≤ 36px       | small  | 10px | 1px    | —    | 8px   | 1px          |
+ *   | 40–72px      | medium | 20px | 2px    | 12px | 16px  | 1.5px        |
+ *   | ≥ 96px       | large  | 32px | 4px    | 18px | 24px  | 2px          |
+ *
+ * "Field" is the dot's inner field — the dot minus both borders — that the
+ * shape glyph is drawn into; see `GLYPH_STROKE_WIDTH` for the stroke ladder.
  *
  * Icons are not rendered at the smallest tier — there isn't enough
- * room for them to be legible.
+ * room for them to be legible. The built-in shape glyphs (see
+ * `glyphShapeMap`) do render there, so status stays distinguishable
+ * without colour at every size.
  */
 function resolveStatusDotSize(avatarSize: number): {
   dotSize: number;
   borderWidth: number;
   iconSize: number;
+  tier: StatusDotSizeTier;
 } {
   if (avatarSize <= 36) {
-    return {dotSize: 10, borderWidth: 1, iconSize: 0};
+    return {dotSize: 10, borderWidth: 1, iconSize: 0, tier: 'small'};
   }
   if (avatarSize <= 72) {
-    return {dotSize: 20, borderWidth: 2, iconSize: 12};
+    return {dotSize: 20, borderWidth: 2, iconSize: 12, tier: 'medium'};
   }
-  return {dotSize: 32, borderWidth: 4, iconSize: 18};
+  return {dotSize: 32, borderWidth: 4, iconSize: 18, tier: 'large'};
 }
 
 /**
@@ -65,6 +77,13 @@ function resolveStatusDotSize(avatarSize: number): {
  *   }
  * }
  * ```
+ *
+ * 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;
@@ -80,12 +99,14 @@ export type AvatarStatusDotVariant = keyof AvatarStatusDotVariantMap;
 export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
-   * The semantic color variant of the dot.
-   * - `success` — green dot (e.g. online, accepted)
-   * - `neutral` — gray dot (e.g. offline, pending)
-   * - `error` — red dot (e.g. busy, rejected)
+   * The semantic variant of the dot. Each variant pairs a colour with a
+   * distinct built-in shape so status is never conveyed by colour alone
+   * (WCAG 2.1 SC 1.4.1):
+   * - `success` — filled green dot (e.g. online, accepted)
+   * - `neutral` — grey ring (e.g. away, offline, pending)
+   * - `error` — red dot with a minus bar (e.g. busy, do not disturb)
    *
-   * Matches the `variant` convention from `StatusDot`.
+   * Matches the `variant` naming convention from `StatusDot`.
    * @default 'success'
    */
   variant?: AvatarStatusDotVariant;
@@ -93,6 +114,11 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
    * Accessible label for the status dot.
    * Describes the meaning of the indicator for screen readers
    * (e.g. "Online", "Accepted", "John Doe is busy").
+   *
+   * Note: inside an Avatar the label is currently not announced — the
+   * Avatar root is `role="img"`, which prunes descendant semantics.
+   * Pass it anyway; composing status into the avatar's accessible name
+   * is a planned Avatar-level fix.
    */
   label?: string;
   /**
@@ -101,6 +127,14 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
    * The icon is automatically sized to fit the dot and hidden
    * at the smallest avatar sizes where there isn't enough room.
    *
+   * A rendered icon replaces the variant's built-in shape glyph, so use a
+   * different icon per status — the same icon on every variant leaves the
+   * statuses distinguishable by colour alone (WCAG 1.4.1). At the smallest
+   * avatar sizes the built-in glyph still shows instead of the icon.
+   * Booleans and empty strings are ignored (safe for `cond && <Icon />`),
+   * but a component that renders nothing still counts as an icon and
+   * suppresses the glyph.
+   *
    * @example
    * ```
    * <AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />
@@ -119,20 +153,29 @@ const styles = stylex.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
+  // Each variant sets both the plate colour and the ink colour. Everything
+  // drawn on the dot — the shape glyph and any user `icon` — paints from
+  // `currentColor`, so the two can never drift out of contrast.
   success: {
     backgroundColor: colorVars['--color-success'],
+    color: colorVars['--color-background-surface'],
   },
+  // The ring variant inverts: a hollow shape only reads as hollow if its
+  // interior is not the variant colour, so the plate is surface and the
+  // colour moves to the stroke. This also keeps a user `icon` legible on
+  // it — surface ink on a surface plate would be invisible.
   neutral: {
-    backgroundColor: colorVars['--color-text-secondary'],
+    backgroundColor: colorVars['--color-background-surface'],
+    color: colorVars['--color-text-secondary'],
   },
   error: {
     backgroundColor: colorVars['--color-error'],
+    color: colorVars['--color-background-surface'],
   },
   icon: {
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    color: colorVars['--color-background-surface'],
     lineHeight: 0,
   },
 });
@@ -157,10 +200,112 @@ const variantStyleMap: Partial<
   error: styles.error,
 };
 
+/**
+ * Built-in shape glyph per variant, so each status differs by shape and not
+ * only by colour (WCAG 2.1 SC 1.4.1). The glyph is a stroked inline SVG
+ * painted in `currentColor`:
+ * - `ring` — a stroked circle on a surface plate; the dot reads as hollow
+ *   (away/offline).
+ * - `minus` — a round-capped bar across the filled dot; the dot reads as
+ *   "do not disturb" (busy).
+ *
+ * `success` stays the plain filled dot — filled, hollow, and barred are the
+ * three distinct fill topologies. Custom augmented variants have no entry
+ * and render no glyph; see the `AvatarStatusDotVariantMap` docs.
+ */
+type AvatarStatusDotGlyphShape = 'ring' | 'minus';
+
+const glyphShapeMap: Partial<
+  Record<AvatarStatusDotVariant, AvatarStatusDotGlyphShape>
+> = {
+  neutral: 'ring',
+  error: 'minus',
+};
+
+/**
+ * Glyph stroke weight per tier, in px of the dot's inner field.
+ *
+ * Roughly `field / 12`, floored at 1px so the smallest tier stays visible.
+ * That lands on the 1 / 1.5 / 2 ladder the rest of the system draws with —
+ * `Icon`'s default set strokes at 1.5 in a 24 viewBox, as does the
+ * `CheckboxInput` checkmark — rather than the 25% band a CSS box cutout
+ * produced, which was several times heavier than any other glyph we ship.
+ */
+const GLYPH_STROKE_WIDTH: Record<StatusDotSizeTier, number> = {
+  small: 1,
+  medium: 1.5,
+  large: 2,
+};
+
+/** Fraction of the inner field the minus bar spans, cap to cap. */
+const MINUS_BAR_SPAN = 0.75;
+
+/**
+ * The built-in shape glyph, drawn as a stroked inline SVG in `currentColor`.
+ *
+ * Stroking (rather than a CSS box) is what buys sub-pixel control and round
+ * line caps, so the mark stays intentional at every tier — including the
+ * 10px dot, where a box cutout can only land on whole pixels.
+ *
+ * `viewBox` is one user unit per px of the inner field, so every value here
+ * is literal px.
+ */
+function StatusDotGlyph({
+  shape,
+  field,
+  stroke,
+}: {
+  shape: AvatarStatusDotGlyphShape;
+  field: number;
+  stroke: number;
+}) {
+  const center = field / 2;
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox={`0 0 ${field} ${field}`}
+      width={field}
+      height={field}
+      fill="none"
+      {...themeProps('avatar-status-dot-glyph', {shape})}>
+      {shape === 'ring' ? (
+        // Radius is to the stroke centreline, so the ring's outer edge lands
+        // exactly on the inner field and never clips against the border.
+        <circle
+          cx={center}
+          cy={center}
+          r={(field - stroke) / 2}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={stroke}
+        />
+      ) : (
+        // Ends inset by half the stroke so the round caps land inside the
+        // span rather than overhanging it.
+        <line
+          x1={(field * (1 - MINUS_BAR_SPAN)) / 2 + stroke / 2}
+          y1={center}
+          x2={(field * (1 + MINUS_BAR_SPAN)) / 2 - stroke / 2}
+          y2={center}
+          stroke="currentColor"
+          strokeWidth={stroke}
+          strokeLinecap="round"
+        />
+      )}
+    </svg>
+  );
+}
+
 /**
  * A status indicator dot that automatically scales to match the parent
  * Avatar's size.
  *
+ * Each variant pairs a colour with a distinct built-in shape (filled dot,
+ * ring, minus bar) so status stays distinguishable without colour
+ * perception (WCAG 2.1 SC 1.4.1). Themes can target the shape glyph via
+ * the `astryx-avatar-status-dot-glyph` class and its `data-shape`
+ * attribute.
+ *
  * Must be used inside an Avatar's `status` prop so it can read
  * the avatar size from context.
  *
@@ -189,7 +334,12 @@ export function AvatarStatusDot({
   ...props
 }: AvatarStatusDotProps) {
   const avatarSize = use(AvatarSizeContext);
-  const {dotSize, borderWidth, iconSize} = resolveStatusDotSize(avatarSize);
+  const {dotSize, borderWidth, iconSize, tier} =
+    resolveStatusDotSize(avatarSize);
+  const showsIcon = isRenderable(icon) && iconSize > 0;
+  // A rendered icon is itself a non-colour mark; overlaying both cutouts in
+  // the dot's small inner field would make each illegible.
+  const glyphShape = showsIcon ? undefined : glyphShapeMap[variant];
 
   return (
     <div
@@ -207,13 +357,20 @@ export function AvatarStatusDot({
         className,
         style,
       )}>
-      {icon && iconSize > 0 && (
+      {showsIcon && (
         <span
           aria-hidden="true"
           {...stylex.props(styles.icon, dynamicStyles.iconSize(iconSize))}>
           {icon}
         </span>
       )}
+      {glyphShape && (
+        <StatusDotGlyph
+          shape={glyphShape}
+          field={dotSize - borderWidth * 2}
+          stroke={GLYPH_STROKE_WIDTH[tier]}
+        />
+      )}
     </div>
   );
 }

package/src/Banner/Banner.doc.mjs

@@ -81,6 +81,13 @@ export const docs = {
         'Container type: card has border-radius; section is full-width with no border-radius for page-level use.',
       default: "'card'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. Use for a floating banner that hovers above content; `none` is the default inline banner. A `card`-container banner rounds its shadow to match.',
+      default: "'none'",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -157,6 +164,7 @@ export const docsZh = {
     {name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用；无论是否提供此回调，横幅都会自动隐藏。'},
     {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。'},
     {name: 'container', type: "'card' | 'section'", description: '视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。', default: "'card'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。', default: "'none'"},
     {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},
     {name: 'defaultIsExpanded', type: 'boolean', description: '内容区域（children）是否初始展开。仅在提供 children 时相关。', default: 'false'},
     {
@@ -230,6 +238,7 @@ export const docsDense = {
     onDismiss: 'dismiss callback; banner self-hides regardless',
     endContent: 'end-aligned action in header, typically button/link',
     container: 'card=border-radius; section=full-width no radius for page-level',
+    elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
     children: 'content in card-bg area below colored header',
     xstyle: 'StyleX layout customization via stylex.create()',
   },

package/src/Banner/Banner.test.tsx

@@ -368,4 +368,34 @@ describe('Banner', () => {
     );
     expect(screen.getByTestId('custom-chevron')).toBeInTheDocument();
   });
+
+  describe('elevation', () => {
+    it('renders a distinct root class for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Banner status="info" title="Heads up" elevation={elevation} />,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <Banner status="info" title="Heads up" />,
+      );
+      const {container: none} = render(
+        <Banner status="info" title="Heads up" elevation="none" />,
+      );
+      expect(def.firstElementChild!.className).toBe(
+        none.firstElementChild!.className,
+      );
+    });
+  });
 });

package/src/Banner/Banner.tsx

@@ -46,8 +46,10 @@ import {
   borderVars,
   durationVars,
   easeVars,
+  shadowVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import type {Elevation} from '../utils/types';
 import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -157,6 +159,13 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
    * @default 'card'
    */
   container?: BannerContainer;
+  /**
+   * Resting elevation — the shadow depth the banner sits at. Use for a
+   * floating banner that hovers above content. `none` is the default inline
+   * banner.
+   * @default 'none'
+   */
+  elevation?: Elevation;
   /**
    * Whether the content area (children) starts expanded.
    * Only relevant when children are provided.
@@ -215,6 +224,11 @@ const styles = stylex.create({
     flexDirection: 'column',
     fontFamily: 'inherit',
   },
+  // When elevated, a card-container banner rounds its root so the shadow
+  // follows the same silhouette as the header/content border-radius.
+  rootElevatedCard: {
+    borderRadius: radiusVars['--radius-container'],
+  },
   // Header area — colored status background with icon, title, description, actions
   // This is the primary theme target ('banner')
   header: {
@@ -323,6 +337,18 @@ const statusStyles = stylex.create({
   },
 });
 
+// Resting elevation for the banner. Applied to the root so the shadow wraps
+// the whole banner (header + optional content). 'none' is the default and
+// leaves the layout-only root untouched. For the `card` container the root is
+// rounded (rootElevatedCard) so the shadow follows the card silhouette; the
+// full-width `section` container stays square.
+const elevationStyles = stylex.create({
+  none: {boxShadow: 'none'},
+  low: {boxShadow: shadowVars['--shadow-low']},
+  med: {boxShadow: shadowVars['--shadow-med']},
+  high: {boxShadow: shadowVars['--shadow-high']},
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -381,6 +407,7 @@ export function Banner({
   onDismiss,
   endContent,
   container = 'card',
+  elevation = 'none',
   defaultIsExpanded = false,
   children,
   xstyle,
@@ -429,7 +456,16 @@ export function Banner({
     <div
       ref={ref}
       role={role}
-      {...mergeProps(stylex.props(styles.root, xstyle), className, style)}
+      {...mergeProps(
+        stylex.props(
+          styles.root,
+          elevationStyles[elevation],
+          isCard && elevation !== 'none' && styles.rootElevatedCard,
+          xstyle,
+        ),
+        className,
+        style,
+      )}
       {...rest}>
       {/* Header: colored status background — primary theme target ('banner') */}
       <div
@@ -474,8 +510,16 @@ export function Banner({
               <Button
                 variant="ghost"
                 size="sm"
-                label={isExpanded ? t('@astryx.banner.collapse') : t('@astryx.banner.expand')}
-                tooltip={isExpanded ? t('@astryx.banner.collapse') : t('@astryx.banner.expand')}
+                label={
+                  isExpanded
+                    ? t('@astryx.banner.collapse')
+                    : t('@astryx.banner.expand')
+                }
+                tooltip={
+                  isExpanded
+                    ? t('@astryx.banner.collapse')
+                    : t('@astryx.banner.expand')
+                }
                 icon={
                   <span
                     {...stylex.props(

package/src/Breadcrumbs/BreadcrumbItem.doc.mjs

@@ -45,6 +45,18 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'menu',
+      type: 'DropdownMenuOption[] | ReactNode',
+      description:
+        'Menu opened when the item is activated, using the same item API as DropdownMenu/MoreMenu/ContextMenu (a DropdownMenuOption[] array or composed DropdownMenuItem children). Renders a link-styled menu trigger with a chevron and aria-haspopup="menu". Takes precedence over href/onClick.',
+    },
+    {
+      name: 'menuSize',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        "Size passed to the menu items. Defaults from the breadcrumb variant ('supporting' → 'sm', otherwise 'md').",
+    },
     {
       name: 'as',
       type: 'LinkComponentType',
@@ -86,6 +98,18 @@ export const docsZh = {
       type: 'ReactNode',
       description: '在项目标签前渲染的图标。',
     },
+    {
+      name: 'menu',
+      type: 'DropdownMenuOption[] | ReactNode',
+      description:
+        '激活项目时打开的菜单，使用与 DropdownMenu/MoreMenu/ContextMenu 相同的项目 API（DropdownMenuOption[] 数组或组合的 DropdownMenuItem 子元素）。渲染为带 chevron 和 aria-haspopup="menu" 的链接样式触发器。优先于 href/onClick。',
+    },
+    {
+      name: 'menuSize',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        "传递给菜单项的尺寸。默认根据面包屑变体推断（'supporting' → 'sm'，否则 'md'）。",
+    },
     {
       name: 'as',
       type: 'LinkComponentType',
@@ -105,6 +129,8 @@ export const docsDense = {
     onClick: 'click handler',
     isCurrent: 'marks current page w/ aria-current="page"',
     startIcon: 'icon before label',
+    menu: 'DropdownMenuOption[] | children; opens a menu trigger (aria-haspopup="menu"); reuses the DropdownMenu item API',
+    menuSize: "menu item size; defaults from variant (supporting→sm, else md)",
     as: 'custom link component; overrides LinkProvider default',
   },
 };