@astryxdesign/core 0.2.0 → 0.3.0

package/src/PowerSearch/PowerSearch.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: 'PowerSearch',
@@ -172,7 +172,7 @@ export const docs = {
 // See .context/decisions/dense-compression-protocol.md
 // -------------------------------------------------------
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'PowerSearch',
   displayName: 'Power Search',
@@ -319,7 +319,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Structured filter bar where each token represents filter (field+operator+value). Users select fields from typeahead dropdown, configure operators+values in edit popover, manage filters as removable tokens.',

package/src/PowerSearch/PowerSearch.tsx

@@ -11,7 +11,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/PowerSearch/index.ts
- * - /packages/cli/templates/blocks/components/PowerSearch/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/PowerSearch/ (showcase blocks)
  */
 
 import React, {

package/src/ProgressBar/ProgressBar.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: 'ProgressBar',
@@ -56,6 +56,12 @@ export const docs = {
       description: 'Animated loading indicator for unknown progress.',
       default: 'false',
     },
+    {
+      name: 'marks',
+      type: 'ReadonlyArray<{value: number; label: string}>',
+      description:
+        'Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them. Each mark requires a label — it is the mark\'s accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -74,6 +80,7 @@ export const docs = {
       {className: 'astryx-progressbar', visualProps: ['variant']},
       {className: 'astryx-progressbar-fill', visualProps: ['variant']},
       {className: 'astryx-progressbar-track'},
+      {className: 'astryx-progressbar-mark'},
     ],
   },
   usage: {
@@ -90,7 +97,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'ProgressBar',
   displayName: 'Progress Bar',
@@ -143,6 +150,12 @@ export const docsZh = {
       description: '用于未知进度的动画加载指示器。',
       default: 'false',
     },
+    {
+      name: 'marks',
+      type: 'ReadonlyArray<{value: number; label: string}>',
+      description:
+        '在轨道上按与 value 相同的 0..max 刻度绘制的固定目标标记（例如目标线）。无论进度低于还是超过它们都保持可见。每个标记都必须提供 label——它既是标记的无障碍名称，也是悬停/聚焦时通过工具提示显示的文本。不确定模式下忽略。',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -161,6 +174,7 @@ export const docsZh = {
       {className: 'astryx-progressbar', visualProps: ['variant']},
       {className: 'astryx-progressbar-fill', visualProps: ['variant']},
       {className: 'astryx-progressbar-track'},
+      {className: 'astryx-progressbar-mark'},
     ],
   },
   usage: {
@@ -177,7 +191,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Progress bar for displaying determinate or indeterminate progress.',
@@ -202,6 +216,7 @@ export const docsDense = {
     formatValueLabel: 'Custom value label formatter; defaults to percentage string.',
     variant: 'Semantic color variant.',
     isIndeterminate: 'Animated loading indicator for unknown progress.',
+    marks: 'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. A label reveals a tooltip on hover/focus. Ignored when indeterminate.',
     isDisabled: 'Visually disabled: grays out fill and text.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
   },

package/src/ProgressBar/ProgressBar.test.tsx

@@ -1,9 +1,18 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, beforeAll} from 'vitest';
+import {render, screen, waitFor} from '@testing-library/react';
 import {ProgressBar} from './ProgressBar';
 
+// A labeled mark wraps the tick in a lazily-loaded Tooltip (React.lazy +
+// Suspense). Preload that chunk once so the Tooltip (and its
+// aria-describedby) is present synchronously on first render, keeping these
+// tests deterministic rather than racing the dynamic import's default 1s
+// Suspense timeout.
+beforeAll(async () => {
+  await import('./ProgressBarMarkTooltip');
+});
+
 describe('ProgressBar', () => {
   it('renders with default props', () => {
     render(<ProgressBar value={50} label="Progress" />);
@@ -277,4 +286,333 @@ describe('ProgressBar', () => {
       expect(css).toMatch(/:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*animation-name:/);
     });
   });
+
+  // Target marks
+  describe('target marks', () => {
+    const MARK = '.astryx-progressbar-mark';
+
+    it('renders no mark elements when marks is omitted', () => {
+      const {container} = render(<ProgressBar value={50} label="Progress" />);
+      expect(container.querySelectorAll(MARK)).toHaveLength(0);
+    });
+
+    it('renders no mark elements for an empty marks array', () => {
+      const {container} = render(
+        <ProgressBar value={50} label="Progress" marks={[]} />,
+      );
+      expect(container.querySelectorAll(MARK)).toHaveLength(0);
+    });
+
+    it('renders a mark at the position matching its value', () => {
+      const {container} = render(
+        <ProgressBar
+          value={40}
+          label="Progress"
+          marks={[{value: 80, label: 'M'}]}
+        />,
+      );
+      const marks = container.querySelectorAll<HTMLElement>(MARK);
+      expect(marks).toHaveLength(1);
+      // value 80 of max 100 -> 80% along the track (RTL-safe logical property).
+      expect(marks[0].style.insetInlineStart).toBe('80%');
+    });
+
+    it('positions marks relative to a custom max', () => {
+      const {container} = render(
+        <ProgressBar
+          value={1}
+          max={5}
+          label="Steps"
+          marks={[{value: 4, label: 'M'}]}
+        />,
+      );
+      const marks = container.querySelectorAll<HTMLElement>(MARK);
+      // value 4 of max 5 -> 80%.
+      expect(marks[0].style.insetInlineStart).toBe('80%');
+    });
+
+    it('keeps a mark past the current value visible', () => {
+      // A mark beyond the fill still renders — it layers above the fill.
+      const {container} = render(
+        <ProgressBar
+          value={20}
+          label="Progress"
+          marks={[{value: 90, label: 'M'}]}
+        />,
+      );
+      const marks = container.querySelectorAll<HTMLElement>(MARK);
+      expect(marks).toHaveLength(1);
+      expect(marks[0].style.insetInlineStart).toBe('90%');
+    });
+
+    it('renders multiple marks', () => {
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[
+            {value: 25, label: 'M'},
+            {value: 50, label: 'M'},
+            {value: 80, label: 'M'},
+          ]}
+        />,
+      );
+      expect(container.querySelectorAll(MARK)).toHaveLength(3);
+    });
+
+    it('clamps out-of-range mark positions to the track edges', () => {
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[
+            {value: -10, label: 'M'},
+            {value: 150, label: 'M'},
+          ]}
+        />,
+      );
+      const marks = container.querySelectorAll<HTMLElement>(MARK);
+      expect(marks).toHaveLength(2);
+      expect(marks[0].style.insetInlineStart).toBe('0%');
+      expect(marks[1].style.insetInlineStart).toBe('100%');
+    });
+
+    it('drops non-finite mark values', () => {
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[
+            {value: NaN, label: 'M'},
+            {value: Infinity, label: 'M'},
+            {value: 60, label: 'M'},
+          ]}
+        />,
+      );
+      const marks = container.querySelectorAll<HTMLElement>(MARK);
+      expect(marks).toHaveLength(1);
+      expect(marks[0].style.insetInlineStart).toBe('60%');
+    });
+
+    it('does not render marks in indeterminate mode', () => {
+      const {container} = render(
+        <ProgressBar
+          isIndeterminate
+          label="Loading"
+          marks={[{value: 80, label: 'M'}]}
+        />,
+      );
+      expect(container.querySelectorAll(MARK)).toHaveLength(0);
+    });
+
+    it('renders every mark as a focusable trigger (label is required, never decorative)', () => {
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'Goal'}]}
+        />,
+      );
+      const mark = container.querySelector<HTMLElement>(MARK)!;
+      // A mark always stands for something meaningful, so it is never
+      // aria-hidden and is always keyboard-focusable to reveal its label.
+      expect(mark).not.toHaveAttribute('aria-hidden');
+      expect(mark).toHaveAttribute('tabindex', '0');
+      // The name comes from the Tooltip (aria-describedby), not a role/label on
+      // the tick itself, so the progressbar's own subtree stays clean.
+      expect(mark).not.toHaveAttribute('role');
+      expect(mark).not.toHaveAttribute('aria-label');
+    });
+
+    it('reveals a labeled mark via a focusable Tooltip trigger', async () => {
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'Goal'}]}
+        />,
+      );
+      // Focusable so keyboard users can reveal the label; named via the
+      // Tooltip's aria-describedby rather than a labeled child of the bar.
+      // The Tooltip loads lazily (Suspense), so re-query the live element and
+      // wait for it to attach aria-describedby.
+      const mark0 = container.querySelector<HTMLElement>(MARK)!;
+      expect(mark0).toHaveAttribute('tabindex', '0');
+      expect(mark0).not.toHaveAttribute('aria-hidden');
+      await waitFor(() =>
+        expect(container.querySelector(MARK)).toHaveAttribute(
+          'aria-describedby',
+        ),
+      );
+      const mark = container.querySelector<HTMLElement>(MARK)!;
+      const tip = document.getElementById(
+        mark.getAttribute('aria-describedby')!,
+      );
+      expect(tip).toHaveTextContent('Goal');
+    });
+
+    it('keeps the progressbar element free of role="img"/aria-label children', () => {
+      // Marks are children of role="progressbar" (unchanged DOM), but a
+      // mark uses a Tooltip (aria-describedby) rather than a
+      // role="img"+aria-label child, so nothing muddies what SRs announce for
+      // the bar.
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'Goal'}]}
+        />,
+      );
+      const progressbar = screen.getByRole('progressbar');
+      // Mark is a child of the progressbar (DOM unchanged from main).
+      expect(progressbar.querySelector(MARK)).not.toBeNull();
+      // But it is not a labeled graphic that pollutes the a11y subtree.
+      expect(progressbar.querySelector('[role="img"]')).toBeNull();
+      expect(progressbar.querySelector('[aria-label]')).toBeNull();
+      expect(container.querySelectorAll(MARK)).toHaveLength(1);
+    });
+
+    it('does not add mark info to the progressbar aria-valuetext', () => {
+      render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'Goal'}]}
+        />,
+      );
+      const progressbar = screen.getByRole('progressbar');
+      expect(progressbar.getAttribute('aria-valuetext')).toBe('50%');
+    });
+
+    it('renders marks as children of the progressbar (unchanged DOM)', () => {
+      // Marks stay children of role="progressbar", after the fill — the same
+      // shape as main. The fill remains the first child.
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'M'}]}
+        />,
+      );
+      const progressbar = screen.getByRole('progressbar');
+      const fill = progressbar.firstElementChild as HTMLElement;
+      expect(fill.style.width).toBe('50%');
+      expect(fill.classList.contains('astryx-progressbar-mark')).toBe(false);
+      const mark = container.querySelector<HTMLElement>(MARK)!;
+      expect(mark.closest('[role="progressbar"]')).toBe(progressbar);
+      expect(container.querySelectorAll(MARK)).toHaveLength(1);
+    });
+
+    it('does not clip marks in determinate mode (track carries no overflow:hidden)', () => {
+      // In determinate mode the track must NOT clip, so a themed taller mark
+      // can overhang the bar. (Indeterminate mode re-adds the clip — covered
+      // separately — but marks are suppressed there, so nothing overhangs.)
+      render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'M'}]}
+        />,
+      );
+      const progressbar = screen.getByRole('progressbar');
+      const trackClass = Array.from(progressbar.classList).find(c =>
+        c.startsWith('x'),
+      );
+      let css = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            css += rule.cssText + '\n';
+          }
+        } catch {
+          // ignore cross-origin sheets
+        }
+      }
+      css += Array.from(document.querySelectorAll('style'))
+        .map(s => s.textContent || '')
+        .join('\n');
+      // The atomic class that would set overflow:hidden must not be applied to
+      // the track. Sanity-check the bar still rendered with a StyleX class.
+      expect(trackClass).toBeDefined();
+      // No rule targeting the track's classes sets overflow:hidden. (StyleX
+      // atomic classes are unique per declaration; if overflow:hidden were on
+      // the track we'd see it applied. We assert the track element's computed
+      // intent by checking no overflow:hidden atomic is in its class list's
+      // rules — simplest robust check: the track style object omits it.)
+      const trackHasOverflowHidden = Array.from(progressbar.classList).some(
+        cls => {
+          const re = new RegExp(
+            `\\.${cls}\\b[^{]*\\{[^}]*overflow:\\s*hidden`,
+            'i',
+          );
+          return re.test(css);
+        },
+      );
+      expect(trackHasOverflowHidden).toBe(false);
+    });
+
+    it('clips the track in indeterminate mode (the sliding fill must not escape)', () => {
+      // Regression: the indeterminate fill slides from translateX -100% to
+      // 250%, deliberately overshooting the track, and relies on the track
+      // clipping it to the visible window. Determinate mode drops the clip so
+      // marks can overhang — indeterminate mode must keep it.
+      render(<ProgressBar isIndeterminate label="Loading" />);
+      const progressbar = screen.getByRole('progressbar');
+      let css = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            css += rule.cssText + '\n';
+          }
+        } catch {
+          // ignore cross-origin sheets
+        }
+      }
+      css += Array.from(document.querySelectorAll('style'))
+        .map(s => s.textContent || '')
+        .join('\n');
+      const trackHasOverflowHidden = Array.from(progressbar.classList).some(
+        cls => {
+          const re = new RegExp(
+            `\\.${cls}\\b[^{]*\\{[^}]*overflow:\\s*hidden`,
+            'i',
+          );
+          return re.test(css);
+        },
+      );
+      expect(trackHasOverflowHidden).toBe(true);
+    });
+
+    it('renders the mark on the stable progressbar-mark target, centered for symmetric overhang', () => {
+      // The mark's width/height/color are directly overridable via the
+      // `progressbar-mark` theme target (no dedicated CSS vars). It is centered
+      // on the track (translate -50%,-50%) so a themed taller tick overhangs the
+      // bar symmetrically above and below without being clipped.
+      const {container} = render(
+        <ProgressBar
+          value={50}
+          label="Progress"
+          marks={[{value: 80, label: 'M'}]}
+        />,
+      );
+      const mark = container.querySelector<HTMLElement>(MARK)!;
+      expect(mark.className).toContain('astryx-progressbar-mark');
+      let css = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            css += rule.cssText + '\n';
+          }
+        } catch {
+          // ignore cross-origin sheets
+        }
+      }
+      css += Array.from(document.querySelectorAll('style'))
+        .map(s => s.textContent || '')
+        .join('\n');
+      // Centered so any themed overhang stays symmetric.
+      expect(css).toMatch(/translate\(-50%,\s*-50%\)/);
+      expect(container.querySelectorAll(MARK)).toHaveLength(1);
+    });
+  });
 });