@astryxdesign/core 0.4.4 → 0.4.5-canary.1dc3e5d

package/src/FormLayout/FormLayout.tsx

@@ -10,7 +10,10 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (context value shape)
+ * - /packages/core/src/FormLayout/FormLayout.doc.mjs (props table)
  * - /packages/core/src/FormLayout/index.ts (exports if types change)
+ * - /packages/core/src/Field/FieldLabel.tsx (defaultOptionality indicator resolution)
  * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
  */
@@ -19,7 +22,11 @@ import {useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
+import {
+  FormLayoutContext,
+  type FormLayoutDirection,
+  type FormOptionality,
+} from './FormLayoutContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
@@ -82,6 +89,26 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    * @default 'vertical'
    */
   direction?: FormLayoutDirection;
+
+  /**
+   * Which state the form treats as its default, so only the *exception*
+   * carries a visible optional/required indicator. It also resolves each
+   * field's `aria-required` so the unmarked majority is still announced
+   * correctly — but only `aria-required`, never the native `required`
+   * attribute, so a layout default can't switch on browser validation.
+   *
+   * - `'optional'` — fields read as optional; only a field with `isRequired`
+   *   shows an indicator (the "required" one).
+   * - `'required'` — fields read as required; only a field with `isOptional`
+   *   shows an indicator (the "optional" one). Fields without `isOptional`
+   *   expose `aria-required` even though they show no indicator.
+   * - unset — today's behavior: `isRequired` and `isOptional` each show their
+   *   own indicator independently.
+   *
+   * A field that merely restates the default (e.g. `isOptional` under
+   * `'optional'`) shows nothing. An inner `FormLayout` shadows an outer one.
+   */
+  defaultOptionality?: FormOptionality;
 }
 
 // =============================================================================
@@ -109,13 +136,17 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
 export function FormLayout({
   children,
   direction = 'vertical',
+  defaultOptionality,
   xstyle,
   className,
   style,
   ref,
   ...props
 }: FormLayoutProps) {
-  const contextValue = useMemo(() => ({direction}), [direction]);
+  const contextValue = useMemo(
+    () => ({direction, defaultOptionality}),
+    [direction, defaultOptionality],
+  );
 
   return (
     <FormLayoutContext value={contextValue}>

package/src/FormLayout/FormLayoutContext.ts

@@ -5,10 +5,13 @@
 /**
  * @file FormLayoutContext.ts
  * @input Uses React createContext
- * @output Exports FormLayoutContext and FormLayoutDirection type
- * @position Context for form layout direction detection
+ * @output Exports FormLayoutContext, FormLayoutDirection, and FormOptionality types
+ * @position Context for form layout direction + default-optionality detection
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop + context value)
+ * - /packages/core/src/Field/FieldLabel.tsx (indicator resolution)
+ * - /packages/core/src/FormLayout/index.ts (exports if types change)
  */
 
 import {createContext} from 'react';
@@ -22,15 +25,27 @@ import {createContext} from 'react';
  *   of their inputs (settings/admin panel pattern).
  */
 export type FormLayoutDirection =
-  | 'vertical'
-  | 'horizontal'
-  | 'horizontal-labels';
+  'vertical' | 'horizontal' | 'horizontal-labels';
 
 /**
- * Context for detecting which form layout direction a component is rendered in.
- * Children can use this to adapt their rendering based on the parent layout.
+ * Which state a form treats as its default, so only the *exception* carries a
+ * visible optional/required indicator.
+ *
+ * - `'optional'` — fields are optional unless a field opts into `isRequired`;
+ *   only required fields show an indicator.
+ * - `'required'` — fields are required unless a field opts into `isOptional`;
+ *   only optional fields show an indicator.
+ */
+export type FormOptionality = 'optional' | 'required';
+
+/**
+ * Context for detecting which form layout a component is rendered in. Children
+ * can use this to adapt their rendering based on the parent layout — direction
+ * for spatial arrangement, and `defaultOptionality` so a field can suppress the
+ * indicator that merely restates the form-wide default.
  */
 export const FormLayoutContext = createContext<{
   direction: FormLayoutDirection;
+  defaultOptionality?: FormOptionality;
 }>({direction: 'vertical'});
 FormLayoutContext.displayName = 'FormLayoutContext';

package/src/FormLayout/index.ts

@@ -13,5 +13,5 @@
 
 export {FormLayout} from './FormLayout';
 export type {FormLayoutProps} from './FormLayout';
-export type {FormLayoutDirection} from './FormLayoutContext';
+export type {FormLayoutDirection, FormOptionality} from './FormLayoutContext';
 export {FormLayoutContext} from './FormLayoutContext';

package/src/Markdown/Markdown.doc.mjs

@@ -169,6 +169,7 @@ export const docs = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },
@@ -381,6 +382,7 @@ export const docsZh = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },
@@ -396,6 +398,7 @@ export const docsDense = {
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
       { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },
+      { guidance: true, description: 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.' },
       { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
     ],
   },

package/src/Markdown/Markdown.test.tsx

@@ -5,6 +5,7 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import type {ReactNode} from 'react';
 import {Markdown} from './Markdown';
 import type {MarkdownInlinePlugin} from './Markdown';
+import {parseOutlineFromMarkdown} from '../Outline/parseOutlineFromMarkdown';
 
 describe('Markdown', () => {
   it('renders with role="document"', () => {
@@ -23,6 +24,83 @@ describe('Markdown', () => {
     expect(screen.getByText('Heading 2').tagName).toBe('H2');
   });
 
+  describe('heading ids', () => {
+    // Outline's documented contract: an outline item id "should match the
+    // target heading element id". Markdown renders the ids that
+    // useOutlineFromMarkdown derives, so hash navigation resolves.
+    it('renders generated id attributes on headings', () => {
+      render(<Markdown>{'# Overview\n\ncontent\n\n# Installation'}</Markdown>);
+      expect(screen.getByText('Overview')).toHaveAttribute('id', 'overview');
+      expect(screen.getByText('Installation')).toHaveAttribute(
+        'id',
+        'installation',
+      );
+    });
+
+    it('disambiguates duplicate headings with numeric suffixes', () => {
+      render(<Markdown>{'# Setup\n\n# Setup\n\n# Setup'}</Markdown>);
+      const ids = screen.getAllByText('Setup').map(el => el.id);
+      expect(ids).toEqual(['setup', 'setup-1', 'setup-2']);
+    });
+
+    it('renders ids matching parseOutlineFromMarkdown for the same source', () => {
+      // Parity invariant: every id the outline derives must resolve to a
+      // rendered heading with that exact id — including slugified formatting,
+      // duplicate numbering, the empty-slug fallback, and code-fence decoys.
+      const source = [
+        '# **Bold** and _italic_ text',
+        '## Setup',
+        '## Setup',
+        '### !!!',
+        '```',
+        '# not a heading',
+        '```',
+        '## The `useState` hook',
+      ].join('\n\n');
+      const {container} = render(<Markdown>{source}</Markdown>);
+      const outline = parseOutlineFromMarkdown(source);
+      expect(outline.length).toBe(5);
+      for (const item of outline) {
+        const target = container.querySelector(`[id="${item.id}"]`);
+        expect(target, `no rendered heading with id "${item.id}"`).not.toBe(
+          null,
+        );
+        expect(target!.tagName).toMatch(/^H[1-6]$/);
+        expect(target!.textContent?.trim()).toBe(item.label);
+      }
+    });
+
+    it('passes the generated id to a custom heading component', () => {
+      const received: (string | undefined)[] = [];
+      render(
+        <Markdown
+          components={{
+            heading: ({children, id}: {children: ReactNode; id?: string}) => {
+              received.push(id);
+              return <h2 id={id}>{children}</h2>;
+            },
+          }}>
+          {'# Overview\n\n# Overview'}
+        </Markdown>,
+      );
+      expect(received).toEqual(['overview', 'overview-1']);
+    });
+
+    it('does not assign ids to headings nested inside blockquotes', () => {
+      // parseOutlineFromMarkdown only lists top-level headings. If nested
+      // headings consumed slugs too, duplicate numbering would drift and
+      // outline links would land on the wrong heading.
+      const source = '> # Quoted\n\n# Quoted';
+      const {container} = render(<Markdown>{source}</Markdown>);
+      const outline = parseOutlineFromMarkdown(source);
+      expect(outline.map(i => i.id)).toEqual(['quoted']);
+      const [nested, topLevel] = screen.getAllByText('Quoted');
+      expect(container.querySelector('blockquote')).toContainElement(nested);
+      expect(nested).not.toHaveAttribute('id');
+      expect(topLevel).toHaveAttribute('id', 'quoted');
+    });
+  });
+
   it('renders paragraphs as block <div> (never <p>) for composition safety', () => {
     render(<Markdown>{'Hello world'}</Markdown>);
     // Markdown paragraphs render as <div> so block-level inline content

package/src/Markdown/Markdown.tsx

@@ -53,6 +53,9 @@ import {
   parseMarkdownIncremental,
   createIncrementalState,
   trimStreamingArtifacts,
+  inlineText,
+  slugify,
+  uniqueSlug,
 } from './parser';
 import type {BlockNode, InlineNode, IncrementalState} from './parser';
 import {themeProps} from '../utils/themeProps';
@@ -108,6 +111,14 @@ export interface MarkdownComponents {
   heading?: React.ComponentType<{
     level: 1 | 2 | 3 | 4 | 5 | 6;
     children: React.ReactNode;
+    /**
+     * Generated slug for this heading, matching the ids produced by
+     * useOutlineFromMarkdown / parseOutlineFromMarkdown. Render it as the
+     * element's `id` to keep Outline hash navigation working. Undefined for
+     * headings nested inside blockquotes or list items (the outline only
+     * lists top-level headings).
+     */
+    id?: string;
   }>;
   paragraph?: React.ComponentType<{children: React.ReactNode}>;
   image?: React.ComponentType<{src: string; alt: string}>;
@@ -1045,6 +1056,7 @@ function renderBlock(
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
   t: TranslatorFn,
+  headingIdMap?: ReadonlyMap<BlockNode, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1071,10 +1083,15 @@ function renderBlock(
           components,
         ),
       );
+      // Only top-level headings get an id: the map is built from the same
+      // traversal parseOutlineFromMarkdown uses (which skips headings nested
+      // in blockquotes / list items), so rendered ids and outline ids stay
+      // identical — including duplicate-slug numbering.
+      const headingId = headingIdMap?.get(node);
       const HeadingComp = components?.heading;
       if (HeadingComp) {
         return (
-          <HeadingComp key={index} level={level}>
+          <HeadingComp key={index} level={level} id={headingId}>
             {headingChildren}
           </HeadingComp>
         );
@@ -1083,6 +1100,7 @@ function renderBlock(
       return (
         <Tag
           key={index}
+          id={headingId}
           {...mergeProps(
             themeProps('markdown-heading', {density, level}),
             stylex.props(
@@ -1652,6 +1670,27 @@ export function Markdown({
     return parseMarkdown(children, parseOptions);
   }, [display, smoothedText, children, isStreaming, parseOptions]);
 
+  // Assign each top-level heading the slug that parseOutlineFromMarkdown
+  // would derive for it, so Outline hash links built from the same source
+  // always find a matching DOM id. Mirrors that function's traversal exactly:
+  // top-level blocks only, one shared duplicate-numbering sequence.
+  // NOTE: must stay above the `display === 'inline'` early return below —
+  // hooks cannot be conditional.
+  const headingIdMap = useMemo(() => {
+    if (display === 'inline' || blocks.length === 0) {
+      return undefined;
+    }
+    const map = new Map<BlockNode, string>();
+    const counts = new Map<string, number>();
+    for (const block of blocks) {
+      if (block.type === 'heading') {
+        const label = inlineText(block.children).trim();
+        map.set(block, uniqueSlug(slugify(label), counts));
+      }
+    }
+    return map;
+  }, [display, blocks]);
+
   const inlineNodes = useMemo(() => {
     if (display !== 'inline') {
       return [];
@@ -1765,6 +1804,7 @@ export function Markdown({
           inlinePlugins,
           components,
           t,
+          headingIdMap,
         ),
       )}
     </div>

package/src/Markdown/parser.ts

@@ -3,8 +3,10 @@
 /**
  * @file parser.ts
  * @input Markdown string
- * @output Array of MarkdownNode AST nodes
- * @position Core parser; consumed by Markdown.tsx
+ * @output Array of MarkdownNode AST nodes; heading slug helpers
+ *   (inlineText, slugify, uniqueSlug) shared by Markdown rendering and
+ *   Outline's parseOutlineFromMarkdown
+ * @position Core parser; consumed by Markdown.tsx and Outline
  */
 
 // ---------------------------------------------------------------------------
@@ -1815,3 +1817,59 @@ export function parseMarkdownIncremental(
 
   return mergeSettledBlocks(settledBlocks, unsettledBlocks);
 }
+
+// ---------------------------------------------------------------------------
+// Heading slugs
+// ---------------------------------------------------------------------------
+// Single source of truth for the heading id contract: Markdown renders these
+// slugs as `id` attributes on h1–h6, and Outline's parseOutlineFromMarkdown
+// derives its item ids from the same functions, so outline hash links always
+// resolve to a rendered heading by construction.
+
+/** Flatten inline nodes into their plain text content. */
+export function inlineText(nodes: InlineNode[]): string {
+  return nodes
+    .map(node => {
+      switch (node.type) {
+        case 'text':
+        case 'code':
+          return node.content;
+        case 'bold':
+        case 'italic':
+        case 'strikethrough':
+        case 'link':
+          return inlineText(node.children);
+        case 'image':
+          return node.alt;
+        case 'citation':
+        case 'break':
+          return '';
+      }
+    })
+    .join('');
+}
+
+/** Turn heading text into a URL-safe slug (lowercase, hyphen-separated). */
+export function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Disambiguate repeated slugs with a numeric suffix (`setup`, `setup-1`, …).
+ * Empty slugs fall back to `section`. The caller owns the counts map so one
+ * document shares a single numbering sequence.
+ */
+export function uniqueSlug(
+  baseSlug: string,
+  counts: Map<string, number>,
+): string {
+  const fallbackSlug = baseSlug || 'section';
+  const count = counts.get(fallbackSlug) ?? 0;
+  counts.set(fallbackSlug, count + 1);
+  return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
+}

package/src/MultiSelector/MultiSelector.tsx

@@ -73,6 +73,7 @@ import {
 import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
@@ -706,6 +707,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   style,
 }: MultiSelectorProps<T>) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.multiSelector.selectPlaceholder');
   const selectAllLabel =
@@ -1526,7 +1528,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           }
           aria-describedby={ariaDescribedBy}
           aria-labelledby={ariaLabelledBy}
-          aria-required={isRequired ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
           // With a disabledMessage the trigger keeps focusability via

package/src/NumberInput/NumberInput.tsx

@@ -53,6 +53,7 @@ import {getInputARIA} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 
 const styles = stylex.create({
@@ -559,6 +560,7 @@ export function NumberInput({
   ...rest
 }: NumberInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
   const id = useId();
   const inputLabelID = useId();
@@ -927,7 +929,7 @@ export function NumberInput({
           value == null || !formatValue ? undefined : formattedValue
         }
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }

package/src/Outline/Outline.doc.mjs

@@ -166,6 +166,8 @@ import {Outline, useOutlineFromMarkdown} from '@astryxdesign/core/Outline';
 
 function MarkdownOutline({markdown}) {
   // Derives {id, label, level} items from headings in the source.
+  // The Markdown component renders the same generated ids on its
+  // headings, so outline links scroll without any extra wiring.
   const items = useOutlineFromMarkdown(markdown);
   return <Outline items={items} />;
 }

package/src/Outline/parseOutlineFromMarkdown.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file parseOutlineFromMarkdown.ts
- * @input Uses Markdown parser internals and OutlineItem type
+ * @input Uses Markdown parser internals (parseMarkdown + heading slug
+ *   helpers) and OutlineItem type
  * @output Exports parseOutlineFromMarkdown for extracting heading outlines from Markdown
  * @position Pure utility; consumed by useOutlineFromMarkdown and public exports
  *
@@ -11,52 +12,21 @@
  * - /packages/core/src/Outline/index.ts
  */
 
-import {parseMarkdown, type InlineNode} from '../Markdown/parser';
+import {
+  parseMarkdown,
+  inlineText,
+  slugify,
+  uniqueSlug,
+} from '../Markdown/parser';
 import type {OutlineItem} from './types';
 
-function inlineText(nodes: InlineNode[]): string {
-  return nodes
-    .map(node => {
-      switch (node.type) {
-        case 'text':
-        case 'code':
-          return node.content;
-        case 'bold':
-        case 'italic':
-        case 'strikethrough':
-        case 'link':
-          return inlineText(node.children);
-        case 'image':
-          return node.alt;
-        case 'citation':
-        case 'break':
-          return '';
-      }
-    })
-    .join('');
-}
-
-function slugify(value: string): string {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/['"]/g, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
-function uniqueSlug(baseSlug: string, counts: Map<string, number>): string {
-  const fallbackSlug = baseSlug || 'section';
-  const count = counts.get(fallbackSlug) ?? 0;
-  counts.set(fallbackSlug, count + 1);
-  return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
-}
-
 /**
  * Extract heading items from a Markdown string.
  *
  * Uses Markdown's parser so fenced code blocks, tables, lists, and inline
  * formatting are interpreted consistently with rendered Markdown output.
+ * Ids come from the parser's shared slug helpers, so they always match the
+ * `id` attributes Markdown renders on its headings.
  */
 export function parseOutlineFromMarkdown(markdown: string): OutlineItem[] {
   const counts = new Map<string, number>();

package/src/RadioList/RadioList.tsx

@@ -29,6 +29,7 @@ import {spacingVars} from '../theme/tokens.stylex';
 import {Field} from '../Field/Field';
 import type {InputStatus} from '../Field/types';
 import {useTooltip} from '../Tooltip';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -218,6 +219,13 @@ export function RadioList({
 
   const groupRef = useRef<HTMLDivElement>(null);
 
+  // The radiogroup exposes the *effective* required state so a form-wide
+  // `defaultOptionality="required"` is announced even when the group carries no
+  // visible indicator. Individual radios keep their native `required` bound to
+  // the explicit `isRequired` (via context), so a layout default never switches
+  // on browser validation for the group.
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+
   // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
   // controls swallow pointer events, so the tooltip listeners attach to the
   // radiogroup container and the radios stay perceivable via aria-disabled
@@ -387,7 +395,7 @@ export function RadioList({
             .join(' ') || undefined
         }
         aria-invalid={status?.type === 'error' ? true : undefined}
-        aria-required={isRequired || undefined}
+        aria-required={isEffectivelyRequired || undefined}
         {...mergeProps(
           themeProps('radio-list', {orientation, size}),
           stylex.props(

package/src/Selector/Selector.tsx

@@ -71,6 +71,7 @@ import {
 } from './utils';
 import {useCombobox, useSelectedItemOffset} from './hooks';
 import {useTypeahead} from '../hooks/useTypeahead';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {SelectorOption} from './SelectorOption';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
@@ -699,6 +700,7 @@ export function Selector<T extends SelectorOptionType>(
     hasClear: hasClearProp,
     ...rest
   } = props as SelectorPropsClearable<T>;
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
   const searchPlaceholder =
     searchPlaceholderFromProps ?? t('@astryx.selector.searchPlaceholder');
@@ -1345,7 +1347,7 @@ export function Selector<T extends SelectorOptionType>(
           }
           aria-describedby={ariaDescribedBy}
           aria-labelledby={ariaLabelledBy}
-          aria-required={isRequired ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
           // With a disabledMessage the trigger keeps focusability via

package/src/StatusDot/StatusDot.doc.mjs

@@ -33,6 +33,12 @@ export const docs = {
       description:
         'Tooltip text shown on hover to explain the status meaning.',
     },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        'Optional icon rendered centered inside the dot, painted in currentColor (the variant\'s ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -84,6 +90,12 @@ export const docsZh = {
         '启用脉冲动画；尊重 prefers-reduced-motion: reduce 设置。',
       default: 'false',
     },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        '可选图标，居中渲染于圆点内，以 currentColor（变体的前景色）着色。为状态提供非颜色标记，请为每个状态使用不同图标。布尔值和空字符串会被忽略，因此 `cond && <Icon />` 是安全的。与 AvatarStatusDot 的契约一致。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -132,6 +144,7 @@ export const docsDense = {
     label: 'Accessible label via aria-label.',
     isPulsing: 'Pulse animation; respects prefers-reduced-motion: reduce.',
     tooltip: 'Tooltip text on hover to explain status meaning.',
+    icon: 'Optional ReactNode rendered centered in the dot (currentColor ink); a non-color mark for the status, use a different icon per status. Booleans/empty strings ignored (safe for cond && <Icon/>). Same contract as AvatarStatusDot.',
     xstyle: 'StyleX layout styles; must be stylex.create() value.',
   },
 };