An open source design system that's fully customizable and agent ready
TypeScript
feat(Avatar): make fallback initials typography theme-reachable via derived vars (#4292)
이동욱08c278ebf0f0
diff --git a/apps/storybook/stories/Avatar.stories.tsx b/apps/storybook/stories/Avatar.stories.tsxindex cf6161e213..37a18508a4 100644--- a/apps/storybook/stories/Avatar.stories.tsx+++ b/apps/storybook/stories/Avatar.stories.tsx@@ -4,6 +4,7 @@ import type {Meta, StoryObj} from '@storybook/react';import * as stylex from '@stylexjs/stylex';import {Avatar} from '@astryxdesign/core/Avatar';import {AvatarStatusDot} from '@astryxdesign/core/Avatar';+import {Theme, defineTheme} from '@astryxdesign/core/theme';import {spacingVars,typographyVars,@@ -606,116 +607,54 @@ export const NumericSizes: Story = {),};-/**- * By default, hovering (or keyboard-focusing) any named Avatar reveals its- * `name` in a tooltip. No configuration required.- */-export const NameTooltip: Story = {- render: () => (- <div {...stylex.props(styles.storyWrapper)}>- <h4 {...stylex.props(styles.heading)}>- Default name tooltip (hover or focus each avatar)- </h4>- <div {...stylex.props(styles.row)}>- <Avatar- src="https://i.pravatar.cc/150?img=11"- name="Ada Lovelace"- size="lg"- />- <Avatar name="Grace Hopper" size="lg" />- <Avatar- src="https://i.pravatar.cc/150?img=12"- name="Katherine Johnson"- size="lg"- />- </div>- </div>- ),-};+// A theme can re-scope the fallback initials' typography per size tier via the+// Avatar-scoped derived vars — a smaller-per-size type scale, regular weight,+// and a muted secondary-text color on an accent wash fill — without forking the+// component. The default row is unchanged (size × 0.4, medium weight, neutral+// fill); only the themed row opts in.+const fallbackScaleTheme = defineTheme({+ name: 'avatar-fallback-scale',+ components: {+ avatar: {+ base: {+ fontWeight: 'var(--font-weight-normal)',+ color: 'var(--color-text-secondary)',+ backgroundColor: 'var(--color-accent-muted)',+ },+ 'size:xsm': {fontSize: '8px'},+ 'size:sm': {fontSize: '9px'},+ 'size:md': {fontSize: '13px'},+ 'size:lg': {fontSize: '16px'},+ 'size:xl': {fontSize: '40px'},+ },+ },+});-/**- * Pass a string to `tooltip` to show custom text instead of the `name` —- * without wrapping the Avatar in a `Tooltip`. Handy when the display name- * differs from a short handle, or when you want to add a role/title.- */-export const CustomTooltip: Story = {+export const ThemedFallbackScale: Story = {+ name: 'Themed Fallback Type Scale',render: () => (<div {...stylex.props(styles.storyWrapper)}>- <h4 {...stylex.props(styles.heading)}>Custom tooltip text</h4>+ <h4 {...stylex.props(styles.heading)}>Default fallback (size × 0.4)</h4><div {...stylex.props(styles.row)}>- <Avatar- src="https://i.pravatar.cc/150?img=13"- name="alovelace"- tooltip="Ada Lovelace — Mathematician"- size="lg"- />- <Avatar- name="ghopper"- tooltip="Grace Hopper — Rear Admiral"- size="lg"- />+ <Avatar name="TY" size="xsm" />+ <Avatar name="XS" size="sm" />+ <Avatar name="SM" size="md" />+ <Avatar name="MD" size="lg" />+ <Avatar name="LG" size="xl" /></div>- </div>- ),-};-/**- * Set `tooltip={false}` to opt out of the built-in name tooltip — for example- * when you supply your own richer overlay (a `Tooltip` or `HoverCard`) around- * the Avatar and don't want a second popup.- */-export const TooltipDisabled: Story = {- render: () => (- <div {...stylex.props(styles.storyWrapper)}><h4 {...stylex.props(styles.heading)}>- Tooltip disabled (no popup on hover)+ Themed fallback (per-size scale, regular weight, wash fill)</h4>- <div {...stylex.props(styles.row)}>- <Avatar- src="https://i.pravatar.cc/150?img=14"- name="Ada Lovelace"- tooltip={false}- size="lg"- />- <Avatar name="Grace Hopper" tooltip={false} size="lg" />- </div>- </div>- ),-};--/**- * Interactive avatars. `href` renders an `<a>` (native right-click / Cmd+click);- * `onClick` renders a `<button>`. Both get a focus-visible accent ring. A- * meaningful `name`/`alt` is required so the control has an accessible name.- */-export const Interactive: Story = {- render: () => (- <div {...stylex.props(styles.storyWrapper)}>- <div>- <h4 {...stylex.props(styles.heading)}>As a link (href)</h4>- <div {...stylex.props(styles.row)}>- <Avatar name="Ada Lovelace" href="https://example.com/ada" />- <Avatar- name="Grace Hopper"- src="https://i.pravatar.cc/150?img=5"- href="https://example.com/grace"- />- </div>- </div>- <div>- <h4 {...stylex.props(styles.heading)}>As a button (onClick)</h4>+ <Theme theme={fallbackScaleTheme} mode="light"><div {...stylex.props(styles.row)}>- <Avatar- name="Alan Turing"- onClick={() => alert('Open Alan Turing')}- />- <Avatar- name="Katherine Johnson"- src="https://i.pravatar.cc/150?img=9"- onClick={() => alert('Open Katherine Johnson')}- />+ <Avatar name="TY" size="xsm" />+ <Avatar name="XS" size="sm" />+ <Avatar name="SM" size="md" />+ <Avatar name="MD" size="lg" />+ <Avatar name="LG" size="xl" /></div>- </div>+ </Theme></div>),};diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjsindex a763315648..809b844807 100644--- a/packages/core/src/Avatar/Avatar.doc.mjs+++ b/packages/core/src/Avatar/Avatar.doc.mjs@@ -32,6 +32,18 @@ export const docs = {{className: 'astryx-avatar-status-dot', visualProps: ['variant']},{className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},],+ vars: [+ {name: '--_avatar-fallback-font-size', description: 'Initials font size; default is proportional to the avatar size (size × 0.4). Override per size tier (e.g. size:sm) for a custom type scale.', default: 'calc(avatar-size × 0.4)', private: true},+ {name: '--_avatar-fallback-font-weight', description: 'Initials font weight', default: 'var(--font-weight-medium)', private: true},+ {name: '--_avatar-fallback-color', description: 'Fallback text and default-icon color', default: 'var(--color-text-secondary)', private: true},+ {name: '--_avatar-fallback-background', description: 'Fallback wash background fill', default: 'var(--color-neutral)', private: true},+ ],+ derived: [+ {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},+ {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},+ {property: 'color', vars: ['--_avatar-fallback-color']},+ {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},+ ],},description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',props: [diff --git a/packages/core/src/Avatar/Avatar.test.tsx b/packages/core/src/Avatar/Avatar.test.tsxindex d464cbdb0f..4106cc6b8f 100644--- a/packages/core/src/Avatar/Avatar.test.tsx+++ b/packages/core/src/Avatar/Avatar.test.tsx@@ -36,6 +36,19 @@ describe('Avatar', () => {expect(innerImg).toHaveAttribute('alt', '');});+ it('renders fallback initials through the themeable font-size var, not a bare px literal', () => {+ render(<Avatar name="Ada Lovelace" size="sm" data-testid="a" />);+ const initials = screen.getByText('AL');+ // The seam: the dynamic font size resolves to the Avatar-scoped var (with+ // the proportional `size × 0.4` default baked in as the fallback), so a+ // theme can re-scope it per size. A regression to a bare px literal would+ // break theming.+ const style = initials.getAttribute('style') ?? '';+ expect(style).toContain('var(--_avatar-fallback-font-size,');+ // Default still reproduces the proportional scale (sm = 24 × 0.4 = 9.6px).+ expect(style).toMatch(/var\(--_avatar-fallback-font-size,\s*9\.6\d*px\)/);+ });+it('retries a new src after a previous src failed to load', () => {const {rerender} = render(<Avatar name="Ada" src="https://example.com/broken.jpg" />,diff --git a/packages/core/src/Avatar/Avatar.tsx b/packages/core/src/Avatar/Avatar.tsxindex 7f7827d8bb..2a4a297bae 100644--- a/packages/core/src/Avatar/Avatar.tsx+++ b/packages/core/src/Avatar/Avatar.tsx@@ -110,6 +110,11 @@ const styles = stylex.create({position: 'relative',display: 'inline-flex',flexShrink: 0,+ // The wrapper is not clipped (so the status dot can overflow), so it must be+ // rounded itself: a themed fallback background lands on `.astryx-avatar` (the+ // class-bearing wrapper) as well as the internal var, and an unrounded+ // wrapper would show that fill as square corners behind the circular content.+ borderRadius: radiusVars['--radius-full'],},content: {display: 'flex',@@ -130,10 +135,14 @@ const styles = stylex.create({justifyContent: 'center',width: '100%',height: '100%',- backgroundColor: colorVars['--color-neutral'],- color: colorVars['--color-text-secondary'],+ // Fallback surface (initials + default icon). Each property reads an+ // Avatar-scoped internal var so a theme can re-scope the fallback wash and+ // initials weight/color without forking; the defaults reproduce today's+ // exact output. See derivedVarRegistry (avatar) + Avatar.doc.mjs theming.+ backgroundColor: `var(--_avatar-fallback-background, ${colorVars['--color-neutral']})`,+ color: `var(--_avatar-fallback-color, ${colorVars['--color-text-secondary']})`,fontFamily: typographyVars['--font-family-body'],- fontWeight: fontWeightVars['--font-weight-medium'],+ fontWeight: `var(--_avatar-fallback-font-weight, ${fontWeightVars['--font-weight-medium']})`,textTransform: 'uppercase',},status: {@@ -195,8 +204,13 @@ const dynamicStyles = stylex.create({width: size,height: size,}),+ // Initials font size defaults to the proportional `size × ratio` scale but is+ // reachable via the `--_avatar-fallback-font-size` derived var, so a theme can+ // set a per-size type scale (e.g. `components.avatar['size:sm']`).fontSize: (size: number) => ({- fontSize: size * INITIALS_FONT_SIZE_RATIO,+ fontSize: `var(--_avatar-fallback-font-size, ${+ size * INITIALS_FONT_SIZE_RATIO+ }px)`,}),statusPosition: (size: number) => ({bottom: size * CIRCLE_EDGE_OFFSET_RATIO,diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex 94b52e14a3..61d3a3d992 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -186,6 +186,7 @@ function discoverComponents(): ComponentInfo[] {// ---------------------------------------------------------------------------const DIR_TO_REGISTRY_KEY: Record<string, string> = {+ Avatar: 'avatar',Banner: 'banner',Button: 'button',Card: 'card',diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.tsindex 3a037c2f4a..88449e8ee6 100644--- a/packages/core/src/theme/derivedVarRegistry.ts+++ b/packages/core/src/theme/derivedVarRegistry.ts@@ -35,6 +35,12 @@ export interface DerivedVarEntry {* entries share the same property.*/export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {+ avatar: [+ {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},+ {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},+ {property: 'color', vars: ['--_avatar-fallback-color']},+ {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},+ ],banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],button: [{property: 'borderRadius', vars: ['--_button-radius']}],card: [diff --git a/packages/core/src/theme/generateThemeRules.test.ts b/packages/core/src/theme/generateThemeRules.test.tsindex b77d671143..df61188b18 100644--- a/packages/core/src/theme/generateThemeRules.test.ts+++ b/packages/core/src/theme/generateThemeRules.test.ts@@ -385,6 +385,48 @@ describe('derived var expansion', () => {expect(rule).toContain('--_button-radius: 8px');});+ it('emits internal vars for avatar fallback typography (base)', () => {+ const theme = defineTheme({+ name: 'test-derived-avatar',+ components: {+ avatar: {+ base: {+ fontWeight: 'var(--font-weight-normal)',+ color: 'var(--color-text-secondary)',+ backgroundColor: 'var(--color-accent-muted)',+ },+ },+ },+ });+ const rules = generateThemeRules(theme);+ const rule = rules.find(r => r.includes('.astryx-avatar'));+ expect(rule).toBeDefined();+ expect(rule).toContain(+ '--_avatar-fallback-font-weight: var(--font-weight-normal)',+ );+ expect(rule).toContain(+ '--_avatar-fallback-color: var(--color-text-secondary)',+ );+ expect(rule).toContain(+ '--_avatar-fallback-background: var(--color-accent-muted)',+ );+ });++ it('emits a per-size fallback font-size for avatar (size:sm)', () => {+ const theme = defineTheme({+ name: 'test-derived-avatar-size',+ components: {+ avatar: {+ 'size:sm': {fontSize: '9px'},+ },+ },+ });+ const rules = generateThemeRules(theme);+ const rule = rules.find(r => r.includes('.astryx-avatar.sm'));+ expect(rule).toBeDefined();+ expect(rule).toContain('--_avatar-fallback-font-size: 9px');+ });+it('does not emit derived vars for components without registry entries', () => {const theme = defineTheme({name: 'test-no-derived',