@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/src/CodeBlock/CodeBlock.tsx

@@ -3,7 +3,7 @@
 'use client';
 /**
  * @file CodeBlock.tsx
- * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API
+ * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API, SyntaxTheme provider
  * @output Exports CodeBlock component and CodeBlockProps
  * @position Core implementation; read-only syntax-highlighted code display
  */
@@ -11,6 +11,7 @@
 import {
   useInsertionEffect,
   useEffect,
+  useId,
   useRef,
   useState,
   useCallback,
@@ -32,6 +33,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {Icon} from '../Icon';
 import {
   tokenize,
@@ -43,6 +45,7 @@ import type {SyntaxToken, TokenLine} from './tokenizer';
 import {ensureHighlightStyles} from './highlightStyles';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import {themeProps} from '../utils/themeProps';
+import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
 
 // ---------------------------------------------------------------------------
 // Styles
@@ -173,6 +176,17 @@ const styles = stylex.create({
   headerCollapsible: {
     cursor: 'pointer',
     userSelect: 'none',
+    // Restore a keyboard-only focus ring with the standard token/offset so this
+    // disclosure control matches the rest of the system (Collapsible, TabMenu);
+    // otherwise it falls back to the inconsistent UA default outline.
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
   },
   gutter: {
     flexShrink: 0,
@@ -382,6 +396,14 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
     language: string,
   ) => {type: string; start: number; end: number}[];
   highlightMode?: 'auto' | 'ranges' | 'spans';
+  /**
+   * Per-instance syntax theme override. Shorthand for wrapping this block in
+   * `<SyntaxTheme theme={...}>` — accepts a preset from
+   * `@astryxdesign/core/theme/syntax` or a theme created with
+   * `defineSyntaxTheme()`. Without it, the block uses the theme-level syntax
+   * colors from the nearest SyntaxTheme ancestor or `defineTheme({ syntax })`.
+   */
+  syntaxTheme?: SyntaxThemeDefinition;
 }
 
 // ---------------------------------------------------------------------------
@@ -633,6 +655,7 @@ export function CodeBlock({
   container = 'card',
   tokenizer: customTokenizer,
   highlightMode = 'auto',
+  syntaxTheme,
   xstyle,
   className,
   style,
@@ -640,6 +663,7 @@ export function CodeBlock({
   ...props
 }: CodeBlockProps) {
   const [copied, setCopied] = useState(false);
+  const announce = useAnnounce();
 
   const useSpans =
     highlightMode === 'spans' ||
@@ -665,12 +689,15 @@ export function CodeBlock({
     try {
       await navigator.clipboard.writeText(code);
       setCopied(true);
+      // Swapping the button's aria-label alone isn't reliably announced by
+      // screen readers, so confirm the copy via a polite live region.
+      announce('Copied');
       onCopy?.();
       setTimeout(() => setCopied(false), 2000);
     } catch {
       // Clipboard failures leave the copied state unchanged.
     }
-  }, [code, onCopy]);
+  }, [code, onCopy, announce]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   const gutterSizeStyle = size === 'sm' ? styles.gutterSm : styles.gutterMd;
@@ -680,6 +707,11 @@ export function CodeBlock({
 
   const canCollapse = isCollapsible && lines.length >= collapsibleThreshold;
   const [isCollapsed, setIsCollapsed] = useState(false);
+  // Links the collapsible header to the code region it shows/hides so assistive
+  // tech can move from the button to its controlled content (disclosure
+  // pattern). The region stays mounted when collapsed (CSS grid animation), so
+  // this is always a resolvable reference — aria-controls can be unconditional.
+  const regionId = useId();
 
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const scrollStyle: CSSProperties | undefined = maxHeight
@@ -717,6 +749,7 @@ export function CodeBlock({
         role={canCollapse ? 'button' : undefined}
         tabIndex={canCollapse ? 0 : undefined}
         aria-expanded={canCollapse ? !isCollapsed : undefined}
+        aria-controls={canCollapse ? regionId : undefined}
         onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
         onKeyDown={
           canCollapse
@@ -802,7 +835,7 @@ export function CodeBlock({
     </div>
   );
 
-  return (
+  const block = (
     <pre
       ref={ref}
       {...mergeProps(
@@ -820,6 +853,7 @@ export function CodeBlock({
       {headerEl}
       {canCollapse ? (
         <div
+          id={regionId}
           {...stylex.props(
             styles.collapseGrid,
             isCollapsed && styles.collapseGridCollapsed,
@@ -832,6 +866,12 @@ export function CodeBlock({
       {!showHeader && copyButtonEl}
     </pre>
   );
+
+  return syntaxTheme ? (
+    <SyntaxTheme theme={syntaxTheme}>{block}</SyntaxTheme>
+  ) : (
+    block
+  );
 }
 
 CodeBlock.displayName = 'CodeBlock';

package/src/Collapsible/Collapsible.doc.mjs

@@ -16,7 +16,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-collapsible'},
+      {className: 'astryx-collapsible', visualProps: ['dividers', 'density']},
+      {className: 'astryx-collapsible-group', visualProps: ['dividers', 'density']},
     ],
   },
   description: 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent CollapsibleGroup.',
@@ -69,7 +70,8 @@ export const docs = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use dividers="between" on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup dividers for flat lists; don\'t combine both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -90,7 +92,8 @@ export const docsZh = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior.',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use dividers="between" on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup dividers for flat lists; don\'t combine both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -107,7 +110,8 @@ export const docsDense = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use in settings, FAQs, or detail views. Wrap in CollapsibleGroup for accordion behavior.',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use dividers="between" on CollapsibleGroup for FAQ-style lists: built-in row hairlines, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation, or use CollapsibleGroup dividers for flat lists; not both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },

package/src/Collapsible/Collapsible.tsx

@@ -4,15 +4,21 @@
 
 /**
  * @file Collapsible.tsx
- * @input Uses React, StyleX, useCollapsible hook, getIcon, theme tokens
+ * @input Uses React, StyleX, useCollapsible hook, CollapsibleGroupPresentationContext, getIcon, theme tokens
  * @output Exports Collapsible component and CollapsibleProps
  * @position Collapsible content primitive — trigger toggles visibility of children
  *
  * Collapsible is a standalone primitive that makes any content collapsible.
  * It renders a trigger area (always visible) and a content area that toggles.
- * Handles state management, accessibility (aria-expanded), and chevron indicator.
+ * Handles state management, accessibility (aria-expanded + aria-controls linking
+ * the trigger to its content region), and chevron indicator.
  *
  * Works standalone or coordinated by CollapsibleGroup via the `value` prop.
+ * When the surrounding CollapsibleGroup enables `dividers`, each Collapsible
+ * draws its own row chrome (borderBlockStart suppressed on :first-child, plus
+ * density padding) from CollapsibleGroupPresentationContext — StyleX has no
+ * child selectors, so the group cannot draw it from outside. The presentation
+ * context is reset around children so nested collapsibles stay chrome-free.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Collapsible/index.ts (exports)
@@ -21,9 +27,10 @@
  * - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {use, useId, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
+  borderVars,
   colorVars,
   typographyVars,
   fontWeightVars,
@@ -33,6 +40,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {useCollapsible} from './useCollapsible';
+import {CollapsibleGroupPresentationContext} from './CollapsibleGroupContext';
 import {getIcon} from '../Icon/globalIconRegistry';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -57,6 +65,16 @@ const styles = stylex.create({
     color: colorVars['--color-text-primary'],
     textAlign: 'start',
     paddingBlock: 0,
+    // `all: unset` above wipes the UA focus outline; restore a keyboard-only
+    // focus ring using the standard token/offset (WCAG 2.4.7).
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
   },
   // Capsize: trim leading from text triggers
   triggerLabel: {
@@ -87,8 +105,42 @@ const styles = stylex.create({
   content: {
     paddingBlockStart: spacingVars['--spacing-1'],
   },
+  // Group divider chrome — a hairline above every item except the first.
+  // The group's wrapper (or 'all' mode) owns the outer edges.
+  divided: {
+    borderBlockStartWidth: {
+      default: borderVars['--border-width'],
+      ':first-child': '0',
+    },
+    borderBlockStartStyle: 'solid',
+    borderBlockStartColor: colorVars['--color-border'],
+  },
+});
+
+// Density padding for divided/padded accordion rows. paddingBlock mapping
+// follows Table's density scale (spacing-1/2/3); content only pads its end
+// so text doesn't sit on the divider below (block-start stays spacing-1).
+const densityStyles = stylex.create({
+  triggerCompact: {paddingBlock: spacingVars['--spacing-1']},
+  triggerBalanced: {paddingBlock: spacingVars['--spacing-2']},
+  triggerSpacious: {paddingBlock: spacingVars['--spacing-3']},
+  contentCompact: {paddingBlockEnd: spacingVars['--spacing-1']},
+  contentBalanced: {paddingBlockEnd: spacingVars['--spacing-2']},
+  contentSpacious: {paddingBlockEnd: spacingVars['--spacing-3']},
 });
 
+const triggerDensity = {
+  compact: densityStyles.triggerCompact,
+  balanced: densityStyles.triggerBalanced,
+  spacious: densityStyles.triggerSpacious,
+} as const;
+
+const contentDensity = {
+  compact: densityStyles.contentCompact,
+  balanced: densityStyles.contentBalanced,
+  spacious: densityStyles.contentSpacious,
+} as const;
+
 export interface CollapsibleProps extends BaseProps {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
@@ -192,14 +244,25 @@ export function Collapsible({
     value,
   });
 
+  const presentation = use(CollapsibleGroupPresentationContext);
+  const isDivided = presentation != null && presentation.dividers !== 'none';
+  const density = presentation?.density ?? null;
+
   const chevronIcon = getIcon('chevronDown');
 
+  // Links the trigger to the region it shows/hides so assistive tech can move
+  // from the button to its controlled content (disclosure pattern).
+  const contentId = useId();
+
   return (
     <div
       ref={ref}
       {...mergeProps(
-        themeProps('collapsible'),
-        stylex.props(styles.root, xstyle),
+        themeProps('collapsible', {
+          dividers: isDivided ? presentation.dividers : undefined,
+          density: density ?? undefined,
+        }),
+        stylex.props(styles.root, isDivided && styles.divided, xstyle),
         className,
         style,
       )}
@@ -208,7 +271,11 @@ export function Collapsible({
         type="button"
         onClick={toggle}
         aria-expanded={isOpen}
-        {...stylex.props(styles.trigger)}>
+        aria-controls={contentId}
+        {...stylex.props(
+          styles.trigger,
+          density != null && triggerDensity[density],
+        )}>
         <span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
         <span
           {...stylex.props(
@@ -219,10 +286,19 @@ export function Collapsible({
         </span>
       </button>
       <div
-        {...(isOpen
-          ? stylex.props(styles.content)
-          : stylex.props(styles.content, styles.contentHidden))}>
-        {children}
+        id={contentId}
+        {...stylex.props(
+          styles.content,
+          density != null && contentDensity[density],
+          !isOpen && styles.contentHidden,
+        )}>
+        {presentation != null ? (
+          <CollapsibleGroupPresentationContext value={null}>
+            {children}
+          </CollapsibleGroupPresentationContext>
+        ) : (
+          children
+        )}
       </div>
     </div>
   );

package/src/Collapsible/CollapsibleGroup.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Collapsible',
   displayName: 'Collapsible Group',
   isHiddenFromOverview: true,
-  description: 'Coordinates multiple Collapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.',
+  description: 'Coordinates multiple Collapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element unless dividers are enabled.',
   props: [
     {
       name: 'type',
@@ -30,6 +30,17 @@ export const docs = {
       type: '(value: string | string[]) => void',
       description: 'Callback invoked when the set of open items changes.',
     },
+    {
+      name: 'dividers',
+      type: "'between' | 'all' | 'none'",
+      description: "Divider style rendered around the group's items. 'between' draws hairlines between adjacent items; 'all' adds the group's top and bottom edges. When enabled, the group renders a wrapper div and items default to 'balanced' density. Pair with bare Collapsible children; Card-wrapped items provide their own separation.",
+      default: "'none'",
+    },
+    {
+      name: 'density',
+      type: "'compact' | 'balanced' | 'spacious'",
+      description: "Row density controlling trigger and content block padding on the group's items. Defaults to 'balanced' when dividers are shown; otherwise items keep their default unpadded look.",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -52,7 +63,7 @@ export const docsZh = {
   name: 'CollapsibleGroup',
   isHiddenFromOverview: true,
   displayName: 'Collapsible Group',
-  description: '协调多个 Collapsible 实例，使同一时间只有一个（single 模式）或任意数量（multiple 模式）可以展开。不渲染包裹 DOM 元素。',
+  description: '协调多个 Collapsible 实例，使同一时间只有一个（single 模式）或任意数量（multiple 模式）可以展开。除非启用 dividers，否则不渲染包裹 DOM 元素。',
   props: [
     {
       name: 'type',
@@ -75,6 +86,17 @@ export const docsZh = {
       type: '(value: string | string[]) => void',
       description: '展开项目集合变更时调用的回调。',
     },
+    {
+      name: 'dividers',
+      type: "'between' | 'all' | 'none'",
+      description: "渲染在组项目周围的分隔线样式。'between' 仅在相邻项目之间绘制细线；'all' 额外绘制组的顶部和底部边缘。启用后组会渲染一个包裹 div，且项目默认使用 'balanced' 密度。适合搭配裸 Collapsible 子项使用；用 Card 包裹的项目自带视觉分隔。",
+      default: "'none'",
+    },
+    {
+      name: 'density',
+      type: "'compact' | 'balanced' | 'spacious'",
+      description: "控制组内项目触发器和内容块内边距的行密度。显示分隔线时默认为 'balanced'；否则项目保持默认的无内边距外观。",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -88,12 +110,14 @@ export const docsDense = {
   name: 'CollapsibleGroup',
   isHiddenFromOverview: true,
   displayName: 'Collapsible Group',
-  description: 'coordinates multiple Collapsible instances; single or multiple open. no wrapper DOM.',
+  description: 'coordinates multiple Collapsible instances; single or multiple open. no wrapper DOM unless dividers enabled.',
   propDescriptions: {
     type: 'one or many items open simultaneously',
     defaultValue: 'default open item(s) (uncontrolled); string for single, array for multiple',
     value: 'controlled open item(s)',
     onChange: 'callback on open items change',
+    dividers: "row hairlines: 'between' items only, 'all' adds outer edges, 'none' (default); enables wrapper div + 'balanced' density; use bare Collapsible children",
+    density: "row padding 'compact' | 'balanced' | 'spacious'; defaults 'balanced' with dividers, else unpadded",
     children: 'Collapsible instances to coordinate',
   },
 };