@astryxdesign/core 0.2.0 → 0.3.0-canary.1b8b3f2

package/src/Table/useTableRowExpansion.doc.mjs

@@ -1,13 +1,13 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'useTableRowExpansion',
   subComponentOf: 'Table',
   displayName: 'useTableRowExpansion',
   description:
-    'Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set.',
+    'Deprecated: use useTableTreeData + useTableTreeState instead. Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set. Converging with useTableTreeData: new tree tables should prefer useTableTreeData + useTableTreeState, which cover the same affordances with a cycle guard and fine-grained re-render. See the migration example below.',
   props: [
     {
       name: 'expandedKeys',
@@ -60,12 +60,65 @@ export const docs = {
       description: 'Callback when the expand-all header toggle is clicked.',
     },
   ],
+  examples: [
+    {
+      label: 'Migrating to useTableTreeData + useTableTreeState',
+      code: `// useTableRowExpansion and useTableTreeData are converging onto one tree
+// plugin. useTableTreeData is the destination: it adds a cycle guard,
+// per-row fine-grained re-render, and imperative row ARIA, and now covers
+// the same affordances (expand-all header control, whole-row click).
+
+// BEFORE: useTableRowExpansion + useTableRowExpansionState
+const [expandedKeys, setExpandedKeys] = useState(new Set(['root']));
+const {data, expansionConfig} = useTableRowExpansionState({
+  baseData: tree,
+  getChildren: item => item.children ?? [],
+  getRowKey: item => item.id,
+  expandedKeys,
+  setExpandedKeys,
+});
+const expansion = useTableRowExpansion(expansionConfig);
+<Table data={data} columns={columns} idKey="id" plugins={{expansion}} />;
+
+// AFTER: useTableTreeState + useTableTreeData
+const {visibleData, treeConfig} = useTableTreeState({
+  data: tree,                   // nested data, not a flat array
+  idKey: 'id',                  // or a function: idKey={item => item.id}
+  childrenKey: 'children',      // replaces getChildren (default 'children')
+  defaultExpandedIds: ['root'], // uncontrolled; or expandedIds + onExpandedIdsChange
+});
+const tree = useTableTreeData({
+  ...treeConfig,
+  hasExpandAllControl: true,    // was isAllExpanded + onToggleExpandAll
+  hasRowClickExpansion: true,   // same prop name
+});
+<Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;`,
+    },
+    {
+      label: 'Config mapping',
+      code: `// useTableRowExpansion(State)         ->  useTableTreeState / useTableTreeData
+
+// baseData: T[] (nested)              ->  data: T[]                (useTableTreeState)
+// getChildren: item => item.children  ->  childrenKey: 'children'  (property name)
+// getRowKey: item => item.id          ->  idKey: 'id' | (item => item.id)
+// getIsItemExpandable                 ->  isItemExpandable         (same shape)
+// expandedKeys + setExpandedKeys      ->  defaultExpandedIds       (uncontrolled), or
+//                                         expandedIds + onExpandedIdsChange (controlled)
+// getDepth                            ->  removed; depth derives from nesting
+// isAllExpanded + onToggleExpandAll   ->  hasExpandAllControl      (state is computed)
+// hasRowClickExpansion                ->  hasRowClickExpansion     (unchanged)
+
+// Rendering: useTableRowExpansion prepends a dedicated expander column;
+// useTableTreeData decorates the tree column in place (configurable via
+// treeColumnKey). Keyboard and AT users toggle via the chevron in both.`,
+    },
+  ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
+    'Deprecated: use useTableTreeData + useTableTreeState instead. Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
   propDescriptions: {
     expandedKeys: 'Set of currently-expanded row keys.',
     onToggle: 'Called when a row expansion is toggled.',

package/src/Table/useTableRowIndex.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: 'useTableRowIndex',
@@ -37,7 +37,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Returns a TablePlugin that prepends a right-aligned monospaced row-number column. Numbering follows the rendered data order (current sort/filter/page view), 1-based by default. Pass the rendered data array; renderCell only receives the item so the plugin derives ordinals from it.',

package/src/Table/useTableRowStatus.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: 'useTableRowStatus',
@@ -13,13 +13,13 @@ export const docs = {
       name: 'getStatus',
       type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
       description:
-        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray, each mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
       required: true,
     },
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Returns a TablePlugin that prepends a narrow per-row status column: a colored dot, or an icon when provided (shape + color beats color alone for a11y). getStatus maps a row to {color, icon?, label} or null. color is a semantic name (success/error/warning/etc.) mapped to a theme token, or a raw CSS color. label is required (tooltip + accessible name). Memoize getStatus with useCallback.',

package/src/Table/useTableSelection.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: 'useTableSelection',

package/src/Table/useTableSelectionState.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: 'useTableSelectionState',

package/src/Table/useTableSortable.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: 'useTableSortable',

package/src/Table/useTableStickyColumns.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: 'useTableStickyColumns',

package/src/Table/useTableTreeData.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: 'useTableTreeData',
@@ -65,6 +65,13 @@ export const docs = {
       description:
         'Column that carries the indent + expander. Defaults to the first column.',
     },
+    {
+      name: 'hasRowClickExpansion',
+      type: 'boolean',
+      description:
+        'When true, clicking anywhere on an expandable row toggles its expansion, in addition to the chevron. A pointer-only convenience: keyboard and assistive-tech users toggle via the chevron button. Clicks on interactive cell content (buttons, links, form controls) or a text selection do not toggle. Leaf rows stay inert, and it is a no-op on flat data.',
+      default: 'false',
+    },
   ],
   examples: [
     {
@@ -100,5 +107,7 @@ export const docsDense = {
       "aggregate state driving the header toggle: true (all) | false (none) | 'indeterminate' (some).",
     onExpandAll: 'expand every expandable row (header control)',
     onCollapseAll: 'collapse every row (header control)',
+    hasRowClickExpansion:
+      'true => clicking an expandable row body toggles it (in addition to the chevron). Leaves stay inert; no-op on flat data. Defaults to false.',
   },
 };

package/src/Table/useTableTreeState.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: 'useTableTreeState',

package/src/Text/Heading.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: 'Heading',
@@ -33,7 +33,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: 'Text color.',
+      description: 'Text color. Themes may add custom colors.',
       default: "'primary'",
     },
     {
@@ -120,7 +120,7 @@ export const docsZh = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: '文本颜色。',
+      description: '文本颜色。主题可添加自定义颜色。',
       default: "'primary'",
     },
     {
@@ -186,7 +186,7 @@ export const docsDense = {
     type: 'Display variant (display-1/2/3); overrides visual styling from level with display-scale sizing.',
     children: 'Heading content.',
     accessibilityLevel: 'aria-level override when different from level for document outline.',
-    color: 'Text color.',
+    color: 'Text color. Themes may add custom colors.',
     display: "Display type; overridden to 'block' when maxLines>0 or hasCapsize.",
     maxLines: 'Max lines before truncation; 0=none. Shows tooltip if truncated.',
     hasTruncateTooltip: "Tooltip for truncated text; true=default position, false=disabled, or a placement ('above' | 'below' | 'start' | 'end').",

package/src/Text/Text.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: 'Text',
@@ -41,7 +41,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
+      description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
     },
     {
       name: 'weight',
@@ -137,7 +137,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -156,7 +156,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'semantic body text + headings w/ theme-driven type scale, truncation, tabular numbers',
   usage: {

package/src/Text/Text.test.tsx

@@ -9,6 +9,7 @@ import {render, screen} from '@testing-library/react';
 import {describe, it, expect} from 'vitest';
 import {Text} from './Text';
 import type {TextType} from './Text';
+import type {TextColor} from '../theme/types';
 
 describe('Text', () => {
   describe('rendering', () => {
@@ -233,3 +234,44 @@ describe('Text custom types', () => {
     expect(screen.getByText('Muted').className).toContain('secondary');
   });
 });
+
+describe('Text custom colors', () => {
+  it('renders a custom color as a stable class for theme CSS to target', () => {
+    // A theme adds a custom color (e.g. via TextColorMap augmentation +
+    // defineTheme). The rendered element carries the color as a class
+    // (astryx-text.<color>) so `.astryx-text.brand { color: ... }` from the
+    // theme applies — mirroring how custom `type`s work.
+    render(<Text color={'brand' as TextColor}>Branded</Text>);
+    const el = screen.getByText('Branded');
+    expect(el.className).toContain('astryx-text');
+    expect(el.className).toContain('brand');
+  });
+
+  it('does not crash on a custom color (falls back to the primary StyleX baseline)', () => {
+    // colorStyles has no entry for a custom color; the component must resolve a
+    // built-in baseline instead of indexing undefined. Built-in `primary` is
+    // the baseline, so both share its StyleX color class.
+    render(
+      <>
+        <Text color={'brand' as TextColor}>Custom</Text>
+        <Text color="primary">Builtin</Text>
+      </>,
+    );
+    const custom = screen.getByText('Custom');
+    const builtin = screen.getByText('Builtin');
+    // Neither throws, and the custom color reuses primary's baseline StyleX
+    // class (the real color comes from theme CSS via the `brand` class).
+    const primaryAtomic = builtin.className
+      .split(/\s+/)
+      .filter(c => c.startsWith('x'));
+    expect(primaryAtomic.length).toBeGreaterThan(0);
+    for (const cls of primaryAtomic) {
+      expect(custom.className).toContain(cls);
+    }
+  });
+
+  it('still applies built-in colors directly', () => {
+    render(<Text color="accent">Accent</Text>);
+    expect(screen.getByText('Accent').className).toContain('accent');
+  });
+});

package/src/Text/Text.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Text/Text.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Text/index.ts (exports if types change)
  * - /apps/storybook/stories/Text.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Text/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Text/ (showcase blocks)
  */
 
 import {lazy, Suspense, useRef, type ReactNode} from 'react';
@@ -23,6 +23,7 @@ import type {
   BuiltinTextType,
   TextSize,
   TextColor,
+  BuiltinTextColor,
   TextWeight,
   TextDisplay,
   TextJustify,
@@ -185,6 +186,24 @@ function resolveStyleType(type: TextType): BuiltinTextType {
   return 'body';
 }
 
+/**
+ * Resolve the StyleX baseline color. Built-in colors map to their own color
+ * style; custom (theme-defined) colors fall back to the `primary` baseline —
+ * their actual color comes from theme CSS (`.astryx-text.<color>` /
+ * `.astryx-heading.<color>`), which the rendered `color` class targets.
+ *
+ * Exported so Heading applies the same custom-color fallback as Text.
+ */
+export function resolveStyleColor(color: TextColor): BuiltinTextColor {
+  // The `in` guard is a runtime check for consumer-augmented custom colors
+  // (which widen `TextColor` beyond the built-ins via TextColorMap); within
+  // core the two types coincide, so no cast is needed.
+  if (color in colorStyles) {
+    return color;
+  }
+  return 'primary';
+}
+
 /**
  * Semantic text component. Renders text with type-based styling from the theme.
  *
@@ -228,6 +247,11 @@ export function Text({
   // Resolve style type — custom types fall back to 'body' for StyleX baseline
   const styleType = resolveStyleType(type);
 
+  // Resolve style color — custom colors fall back to 'primary' for StyleX
+  // baseline; the real color comes from theme CSS via the rendered `color`
+  // class (see themeProps below).
+  const styleColor = resolveStyleColor(resolvedColor);
+
   // Resolve wordBreak with smart default
   const resolvedWordBreak =
     wordBreak ?? (maxLines === 1 ? 'break-all' : 'break-word');
@@ -257,7 +281,7 @@ export function Text({
         {...mergeProps(
           themeProps('text', {type, size, color: resolvedColor}),
           stylex.props(
-            colorStyles[resolvedColor],
+            colorStyles[styleColor],
             sizeByTypeStyles[styleType],
             size && sizeStyles[size],
             defaultWeightByTypeStyles[styleType],

package/src/Text/index.ts

@@ -7,12 +7,38 @@
  * @position Entry point for Text components
  */
 
-export {
-  Text,
-  type TextProps,
-  type TextType,
-  type TextSize,
-} from './Text';
+/**
+ * Extensible map of text color variants for Text/Heading.
+ *
+ * Themes add custom colors via component overrides in defineTheme; a custom
+ * color renders with the `primary` baseline color from StyleX and receives its
+ * actual color from theme CSS (`.astryx-text.<color>` / `.astryx-heading.<color>`),
+ * exactly like custom text `type`s.
+ *
+ * To add type-safe custom colors, use module augmentation — the same technique
+ * as `ButtonVariantMap` etc.:
+ * ```ts
+ * declare module '@astryxdesign/core/Text' {
+ *   interface TextColorMap {
+ *     brand: true;
+ *     danger: true;
+ *   }
+ * }
+ * ```
+ *
+ * `astryx theme build` generates these augmentations automatically when it
+ * detects new `color:*` values in a theme's Text/Heading component overrides.
+ */
+export interface TextColorMap {
+  primary: true;
+  secondary: true;
+  disabled: true;
+  placeholder: true;
+  accent: true;
+  inherit: true;
+}
+
+export {Text, type TextProps, type TextType, type TextSize} from './Text';
 export {
   Heading,
   type HeadingProps,

package/src/TextArea/TextArea.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: 'TextArea',
@@ -98,7 +98,7 @@ export const docs = {
       name: 'maxLength',
       type: 'number',
       description:
-        'Maximum number of characters allowed. When set, a character counter (current/max) is displayed below the textarea. Does not enforce the limit natively; the counter shows error styling when exceeded.',
+        'Maximum number of characters allowed. When set, a character counter (current/max) is displayed inside the input container, anchored to the bottom-right beneath the text. Does not enforce the limit natively; when exceeded the counter turns red and shows a warning icon (a non-color cue), and screen-reader users hear the remaining/over-limit count announced.',
     },
     {
       name: 'status',
@@ -198,7 +198,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'TextArea',
   displayName: 'Text Area',
@@ -374,7 +374,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Multi-line text input for collecting longer user input.',
   usage: {
@@ -407,7 +407,7 @@ export const docsDense = {
     isLoading: 'Loading state w/ spinner inside input.',
     placeholder: 'Placeholder when textarea empty.',
     rows: 'Visible text rows.',
-    maxLength: 'Max chars allowed. Shows counter (current/max) below textarea. No native enforcement.',
+    maxLength: 'Max chars allowed. Shows counter (current/max) inside the container, bottom-right beneath the text. No native enforcement; over-limit shows red + a warning icon and is announced to screen readers.',
     status: 'Colored border+icon status. Optional floating message below textarea.',
     statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'Tooltip in info icon at label end.',

package/src/TextArea/TextArea.test.tsx

@@ -335,6 +335,23 @@ describe('TextArea', () => {
       expect(messageElement).toHaveAttribute('id');
       expect(describedBy).toContain(messageElement.id);
     });
+
+    it('shows both the loading spinner and the status icon while busy', () => {
+      const {container} = render(
+        <TextArea
+          label="Description"
+          value=""
+          onChange={() => {}}
+          isLoading
+          status={{type: 'error'}}
+        />,
+      );
+      // Matches the other inputs: spinner (role="status") and the status icon
+      // render side by side in the end slot, not mutually exclusively.
+      expect(screen.getByRole('status')).toBeInTheDocument();
+      // Status icon svg is also present alongside the spinner.
+      expect(container.querySelectorAll('svg').length).toBeGreaterThan(0);
+    });
   });
 
   it('renders tooltip info icon when labelTooltip is provided', () => {
@@ -506,7 +523,70 @@ describe('TextArea', () => {
       expect(screen.getByText('5/50')).toBeInTheDocument();
     });
 
-    it('counter has aria-live region for screen reader announcements', () => {
+    it('announces remaining characters politely as the value nears the limit', async () => {
+      const user = userEvent.setup();
+      function Wrapper() {
+        const [val, setVal] = useState('x'.repeat(44));
+        return (
+          <TextArea
+            label="Description"
+            value={val}
+            onChange={setVal}
+            maxLength={50}
+          />
+        );
+      }
+      render(<Wrapper />);
+      // Type one more char to cross into the "near the limit" zone (45/50).
+      await user.type(screen.getByRole('textbox'), 'x');
+      const politeRegion = () =>
+        document.querySelector('[data-astryx-live-region="polite"]');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('5 characters remaining');
+      });
+    });
+
+    it('announces over-limit assertively once the value exceeds the max', async () => {
+      const user = userEvent.setup();
+      function Wrapper() {
+        const [val, setVal] = useState('x'.repeat(50));
+        return (
+          <TextArea
+            label="Description"
+            value={val}
+            onChange={setVal}
+            maxLength={50}
+          />
+        );
+      }
+      render(<Wrapper />);
+      await user.type(screen.getByRole('textbox'), 'x');
+      const assertiveRegion = () =>
+        document.querySelector('[data-astryx-live-region="assertive"]');
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent(
+          '1 character over the limit',
+        );
+      });
+    });
+
+    it('shows a non-color over-limit indicator icon when exceeded', () => {
+      const {container} = render(
+        <TextArea
+          label="Description"
+          value={'x'.repeat(55)}
+          onChange={() => {}}
+          maxLength={50}
+        />,
+      );
+      // The counter renders a warning icon (a shape cue) alongside the red
+      // count, so the over-limit state is not conveyed by color alone.
+      const counter = screen.getByText('55/50').closest('div');
+      expect(counter?.querySelector('svg')).toBeInTheDocument();
+      expect(container).toBeInTheDocument();
+    });
+
+    it('does not show the over-limit indicator icon within the limit', () => {
       render(
         <TextArea
           label="Description"
@@ -515,9 +595,8 @@ describe('TextArea', () => {
           maxLength={50}
         />,
       );
-      const liveRegion = document.querySelector('[aria-live="polite"]');
-      expect(liveRegion).toBeInTheDocument();
-      expect(liveRegion).toHaveTextContent('5 characters remaining');
+      const counter = screen.getByText('45/50').closest('div');
+      expect(counter?.querySelector('svg')).not.toBeInTheDocument();
     });
 
     it('counter is linked to textarea via aria-describedby', () => {
@@ -535,6 +614,22 @@ describe('TextArea', () => {
       expect(counter).toHaveAttribute('id');
       expect(describedBy).toContain(counter.id);
     });
+
+    it('renders the counter inside the input container (same wrapper as textarea)', () => {
+      render(
+        <TextArea
+          label="Description"
+          value="Hello"
+          onChange={() => {}}
+          maxLength={50}
+        />,
+      );
+      const textarea = screen.getByRole('textbox');
+      const counter = screen.getByText('5/50');
+      // The counter now lives inside the bordered input container as a sibling
+      // overlay of the textarea, not below it as an out-of-container element.
+      expect(textarea.parentElement).toBe(counter.parentElement);
+    });
   });
 
   describe('hasAutoFocus prop', () => {
@@ -737,11 +832,15 @@ describe('TextArea', () => {
   });
 });
 
-
 describe('TextArea statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(
-      <TextArea label="Bio" value="" onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+      <TextArea
+        label="Bio"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -751,7 +850,13 @@ describe('TextArea statusVariant forwarding', () => {
 
   it('forwards statusVariant="detached" to the underlying Field status', () => {
     const {container} = render(
-      <TextArea label="Bio" value="" onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+      <TextArea
+        label="Bio"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+        statusVariant="detached"
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',