Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Citation): secondary text, badge pill, live preview (#3508)

AKc395fcad3e65
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
index a9d86e23b8..98aa55ff7f 100644
--- a/apps/docsite/src/__tests__/component-preview-state.test.ts
+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts
@@ -147,6 +147,30 @@ describe('component detail preview state', () => {
expect(getMissingRequiredProps(knobs, state)).toEqual([]);
});
+ it("satisfies Citation's required, non-generatable source prop via playground defaults", () => {
+ const knobs = pickPrimaryProps('Citation', [
+ prop({name: 'source', type: 'CitationSource', required: true}),
+ prop({name: 'number', type: 'number', required: true}),
+ ]);
+
+ // Without a playground default the custom-object `source` prop cannot be
+ // generated, so the properties tab shows the missing-props placeholder
+ // instead of an interactive preview.
+ expect(getMissingRequiredProps(knobs, buildInitialState(knobs))).toEqual([
+ 'source',
+ ]);
+
+ // The doc's playground default seeds a renderable source object.
+ const state = buildInitialState(knobs, {
+ defaults: {
+ source: {title: 'Astryx Design', url: 'https://example.com'},
+ number: 1,
+ },
+ });
+ expect(state.source).toMatchObject({title: 'Astryx Design'});
+ expect(getMissingRequiredProps(knobs, state)).toEqual([]);
+ });
+
it('gives Timestamp a valid date value via playground defaults', () => {
const knobs = pickPrimaryProps('Timestamp', [
prop({name: 'value', type: 'string | number', required: true}),
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 5a83de28d6..2577ffdda1 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -284,6 +284,18 @@ describe('componentRegistry', () => {
});
});
+ it('Citation satisfies its required source prop via playground defaults', () => {
+ const core = components['@astryxdesign/core'];
+ const citation = core.find(c => c.name === 'Citation');
+ expect(citation).toBeDefined();
+ // `source` is a custom object type the preview cannot auto-generate;
+ // without these defaults the properties tab has no interactive preview.
+ expect(citation!.playground?.defaults).toMatchObject({
+ source: {title: 'Astryx Design', url: 'https://example.com'},
+ number: 1,
+ });
+ });
+
it('MetadataListItem declares a playground wrapper for realistic preview structure', () => {
const core = components['@astryxdesign/core'];
const metadataListItem = core.find(c => c.name === 'MetadataListItem');
diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjs
index b115e60f57..164387fb07 100644
--- a/packages/core/src/Citation/Citation.doc.mjs
+++ b/packages/core/src/Citation/Citation.doc.mjs
@@ -56,6 +56,16 @@ export const docs = {
],
},
+ // `source` is a custom object type the docsite preview cannot generate
+ // automatically; without these defaults the properties tab shows the
+ // missing-required-props placeholder instead of an interactive preview.
+ playground: {
+ defaults: {
+ source: {title: 'Astryx Design', url: 'https://example.com'},
+ number: 1,
+ },
+ },
+
props: [
{
name: 'source',
diff --git a/packages/core/src/Citation/Citation.test.tsx b/packages/core/src/Citation/Citation.test.tsx
new file mode 100644
index 0000000000..a4813e9bde
--- /dev/null
+++ b/packages/core/src/Citation/Citation.test.tsx
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Citation.test.tsx
+ * @input Uses React Testing Library, Citation, theme tokens
+ * @output Tests for Citation component
+ */
+
+import {render, screen} from '@testing-library/react';
+import {describe, it, expect} from 'vitest';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {Citation} from './Citation';
+
+// StyleX emits one deterministic atomic class per property/value pair, so an
+// element carries a probe's class exactly when it has the same declaration.
+// The dev-mode debug class (contains "__") varies by source location and is
+// excluded from the comparison.
+const probe = stylex.create({
+ secondaryText: {color: colorVars['--color-text-secondary']},
+ accentText: {color: colorVars['--color-text-accent']},
+ badgeBackground: {backgroundColor: colorVars['--color-accent-muted']},
+});
+
+function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
+ const {className = ''} = stylex.props(style);
+ return className.split(' ').filter(c => c !== '' && !c.includes('__'));
+}
+
+describe('Citation', () => {
+ const source = {title: 'Example Source', url: 'https://example.com'};
+
+ it('renders the source title as a link in the label variant', () => {
+ render(<Citation source={source} number={1} data-testid="citation" />);
+ const el = screen.getByTestId('citation');
+ expect(el.tagName).toBe('A');
+ expect(el).toHaveAttribute('href', 'https://example.com');
+ expect(el).toHaveTextContent('Example Source');
+ });
+
+ it('renders the index as a badge in the number variant', () => {
+ render(
+ <Citation
+ source={source}
+ number={3}
+ variant="number"
+ data-testid="citation"
+ />,
+ );
+ const el = screen.getByTestId('citation');
+ expect(el).toHaveTextContent('3');
+ expect(el).toHaveAttribute('role', 'doc-noteref');
+ expect(el).toHaveAttribute('aria-label', 'Citation 3: Example Source');
+ });
+
+ it('renders as a span when the source has no url', () => {
+ render(
+ <Citation
+ source={{title: 'No link'}}
+ number={1}
+ data-testid="citation"
+ />,
+ );
+ expect(screen.getByTestId('citation').tagName).toBe('SPAN');
+ });
+
+ it('renders astryx-* class names for theme targeting', () => {
+ render(<Citation source={source} number={1} data-testid="citation" />);
+ expect(screen.getByTestId('citation').className).toContain(
+ 'astryx-citation',
+ );
+ });
+
+ it('uses the secondary text color in the label variant', () => {
+ render(<Citation source={source} number={1} data-testid="citation" />);
+ const el = screen.getByTestId('citation');
+ for (const cls of atomicClasses(probe.secondaryText)) {
+ expect(el.classList.contains(cls)).toBe(true);
+ }
+ });
+
+ it('uses the secondary text color, not accent, in the number variant', () => {
+ render(
+ <Citation
+ source={source}
+ number={1}
+ variant="number"
+ data-testid="citation"
+ />,
+ );
+ const el = screen.getByTestId('citation');
+ for (const cls of atomicClasses(probe.secondaryText)) {
+ expect(el.classList.contains(cls)).toBe(true);
+ }
+ for (const cls of atomicClasses(probe.accentText)) {
+ expect(el.classList.contains(cls)).toBe(false);
+ }
+ });
+
+ it('keeps the accent-muted badge background when the source has a url', () => {
+ // `numberHover` must not clobber the base background: a hover-only
+ // conditional without a default replaces the whole property on merge,
+ // leaving linked badges with a transparent pill.
+ render(
+ <Citation
+ source={source}
+ number={1}
+ variant="number"
+ data-testid="citation"
+ />,
+ );
+ const el = screen.getByTestId('citation');
+ for (const cls of atomicClasses(probe.badgeBackground)) {
+ expect(el.classList.contains(cls)).toBe(true);
+ }
+ });
+});
diff --git a/packages/core/src/Citation/Citation.tsx b/packages/core/src/Citation/Citation.tsx
index 289b7fa574..60f9d5c06d 100644
--- a/packages/core/src/Citation/Citation.tsx
+++ b/packages/core/src/Citation/Citation.tsx
@@ -83,6 +83,10 @@ const styles = stylex.create({
},
},
color: {
+ // Explicit default: without it, this hover-only conditional replaces
+ // the base secondary color from `label` (last-wins property merge),
+ // leaving linked citations to inherit the surrounding text color.
+ default: colorVars['--color-text-secondary'],
':hover': {
'@media (hover: hover)': colorVars['--color-text-primary'],
},
@@ -96,7 +100,7 @@ const styles = stylex.create({
fontSize: typeScaleVars['--text-supporting-size'],
fontWeight: fontWeightVars['--font-weight-semibold'],
lineHeight: typeScaleVars['--text-supporting-leading'],
- color: colorVars['--color-text-accent'],
+ color: colorVars['--color-text-secondary'],
backgroundColor: colorVars['--color-accent-muted'],
borderRadius: radiusVars['--radius-full'],
minWidth: spacingVars['--spacing-5'],
@@ -110,6 +114,10 @@ const styles = stylex.create({
},
numberHover: {
backgroundColor: {
+ // Explicit default for the same reason as labelHover's color: a
+ // hover-only conditional replaces the base accent-muted pill from
+ // `number` on merge, leaving linked badges transparent.
+ default: colorVars['--color-accent-muted'],
':hover': {
'@media (hover: hover)': colorVars['--color-overlay-hover'],
},