@djangocfg/ui-tools 2.1.465 → 2.1.466

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.465",
+  "version": "2.1.466",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -334,8 +334,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.465",
-    "@djangocfg/ui-core": "^2.1.465",
+    "@djangocfg/i18n": "^2.1.466",
+    "@djangocfg/ui-core": "^2.1.466",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -418,9 +418,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.9.4"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.465",
-    "@djangocfg/typescript-config": "^2.1.465",
-    "@djangocfg/ui-core": "^2.1.465",
+    "@djangocfg/i18n": "^2.1.466",
+    "@djangocfg/typescript-config": "^2.1.466",
+    "@djangocfg/ui-core": "^2.1.466",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.9",
     "@types/node": "^25.9.5",

package/src/tools/chat/README.md

@@ -1002,6 +1002,7 @@ const PROMPTS: readonly SuggestedPromptItem[] = [
         onPick={(item) => { setValue(item.prompt); focus(); }}
         hero={<Sparkles className="size-6 text-primary" />}
         title="How can I help?"
+        titleLevel={2}
         description="Pick a starter, or just start typing."
       />
     ),
@@ -1009,7 +1010,10 @@ const PROMPTS: readonly SuggestedPromptItem[] = [
 />
 ```
 
-`renderItem` is an escape hatch for one-off chip styling without forking the component.
+The prompt collection uses native `ul`/`li` semantics while each prompt remains
+a button. `titleLevel` defaults to `2`; set it to `3` or `4` when the empty state
+is nested below an existing section heading. `renderItem` is an escape hatch for
+one-off chip styling without forking the component.
 
 ### 3. Headless
 

package/src/tools/chat/shell/SuggestedPrompts.tsx

@@ -30,12 +30,15 @@ export type SuggestedPromptItem = {
 };
 
 export type SuggestedPromptsLayout = 'chips' | 'grid';
+export type SuggestedPromptsTitleLevel = 2 | 3 | 4;
 
 export interface SuggestedPromptsProps {
   items: readonly SuggestedPromptItem[];
   onPick: (item: SuggestedPromptItem) => void;
   /** Optional title above the chips. */
   title?: ReactNode;
+  /** Semantic title level. Defaults to `2`; set it to match the host page outline. */
+  titleLevel?: SuggestedPromptsTitleLevel;
   /** Optional subtitle/description above the chips. */
   description?: ReactNode;
   /** Optional hero element above the title (icon, logo, …). */
@@ -54,6 +57,7 @@ export function SuggestedPrompts({
   items,
   onPick,
   title,
+  titleLevel = 2,
   description,
   hero,
   layout = 'chips',
@@ -62,6 +66,7 @@ export function SuggestedPrompts({
   renderItem,
 }: SuggestedPromptsProps) {
   const hasHeader = hero != null || title != null || description != null;
+  const Title = `h${titleLevel}` as 'h2' | 'h3' | 'h4';
 
   return (
     <section
@@ -78,9 +83,9 @@ export function SuggestedPrompts({
             <div className="text-foreground/90">{hero}</div>
           ) : null}
           {title != null ? (
-            <h3 className="text-base font-semibold text-foreground">
+            <Title className="text-base font-semibold text-foreground">
               {title}
-            </h3>
+            </Title>
           ) : null}
           {description != null ? (
             <p className="max-w-md text-sm leading-snug text-muted-foreground">
@@ -91,35 +96,25 @@ export function SuggestedPrompts({
       ) : null}
 
       {layout === 'grid' ? (
-        <div
-          className="grid w-full max-w-xl grid-cols-1 gap-2 sm:grid-cols-2"
-          role="list"
-        >
-          {items.map((item, idx) =>
-            renderItem ? (
-              <span key={item.id} role="listitem">
-                {renderItem(item, idx)}
-              </span>
-            ) : (
-              <GridCard key={item.id} item={item} onPick={onPick} />
-            ),
-          )}
-        </div>
+        <ul className="m-0 grid w-full max-w-xl list-none grid-cols-1 gap-2 p-0 sm:grid-cols-2">
+          {items.map((item, idx) => (
+            <li key={item.id} className="min-w-0">
+              {renderItem
+                ? renderItem(item, idx)
+                : <GridCard item={item} onPick={onPick} />}
+            </li>
+          ))}
+        </ul>
       ) : (
-        <div
-          className="flex w-full max-w-xl flex-wrap justify-center gap-2"
-          role="list"
-        >
-          {items.map((item, idx) =>
-            renderItem ? (
-              <span key={item.id} role="listitem">
-                {renderItem(item, idx)}
-              </span>
-            ) : (
-              <Chip key={item.id} item={item} onPick={onPick} />
-            ),
-          )}
-        </div>
+        <ul className="m-0 flex w-full max-w-xl list-none flex-wrap justify-center gap-2 p-0">
+          {items.map((item, idx) => (
+            <li key={item.id}>
+              {renderItem
+                ? renderItem(item, idx)
+                : <Chip item={item} onPick={onPick} />}
+            </li>
+          ))}
+        </ul>
       )}
     </section>
   );
@@ -135,7 +130,6 @@ function Chip({
   return (
     <button
       type="button"
-      role="listitem"
       onClick={() => onPick(item)}
       className={cn(
         'inline-flex items-center gap-1.5 rounded-full border border-border',
@@ -166,10 +160,9 @@ function GridCard({
   return (
     <button
       type="button"
-      role="listitem"
       onClick={() => onPick(item)}
       className={cn(
-        'group flex flex-col gap-1 rounded-md border border-border',
+        'group flex h-full w-full flex-col gap-1 rounded-md border border-border',
         'bg-card/60 p-3 text-left',
         'transition-colors duration-150',
         'hover:border-primary/40 hover:bg-card',

package/src/tools/chat/shell/__tests__/SuggestedPrompts.test.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+
+import { act, createElement, type ComponentProps } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SuggestedPrompts, type SuggestedPromptItem } from '../SuggestedPrompts';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+const items: readonly SuggestedPromptItem[] = [
+  { id: 'one', label: 'First prompt', prompt: 'First prompt' },
+  { id: 'two', label: 'Second prompt', prompt: 'Second prompt' },
+];
+
+describe('SuggestedPrompts', () => {
+  const mounted: Array<ReturnType<typeof createRoot>> = [];
+
+  afterEach(() => {
+    act(() => mounted.splice(0).forEach((root) => root.unmount()));
+  });
+
+  function render(props: Partial<ComponentProps<typeof SuggestedPrompts>> = {}) {
+    const container = document.createElement('div');
+    const root = createRoot(container);
+    mounted.push(root);
+    act(() => {
+      root.render(createElement(SuggestedPrompts, {
+        items,
+        onPick: vi.fn(),
+        title: 'Start here',
+        ...props,
+      }));
+    });
+    return container;
+  }
+
+  it('uses native list semantics without overriding button roles', () => {
+    const container = render();
+    const list = container.querySelector('ul');
+
+    expect(list?.children).toHaveLength(2);
+    expect(Array.from(list?.children ?? []).every((item) => item.tagName === 'LI')).toBe(true);
+    expect(container.querySelectorAll('button[role]')).toHaveLength(0);
+  });
+
+  it('defaults to h2 and lets the host select the outline level', () => {
+    expect(render().querySelector('h2')?.textContent).toBe('Start here');
+    expect(render({ titleLevel: 4 }).querySelector('h4')?.textContent).toBe('Start here');
+  });
+});

package/src/tools/data/Tree/README.md

@@ -20,6 +20,9 @@ We tried popular headless tree engines first. They all leak React-integration bu
 5. **CRUD = adapter, not props.** The host app describes how to delete / rename / move / etc. through a single `TreeAdapter<T>` object. Tree owns the UX (dialogs, hotkeys, menus) and calls back into the adapter. No `onDelete`/`onRename`/... prop sprawl.
 6. **Dialogs come from `<DialogProvider>`.** Tree never re-implements its own dialogs. Built-in CRUD flows resolve `window.dialog` (installed by `@djangocfg/ui-core/lib/dialog-service`). If the host app hasn't mounted it, CRUD flows silently no-op with a dev-mode warning — Tree itself still renders.
 7. **CSS-variable theming.** Density, sizes, gaps, indent — all exposed as `--tree-*` variables on the root. Override in any consumer without re-implementing components.
+8. **Honest empty semantics.** An empty collection is announced as a status and
+   does not expose an invalid, focusable ARIA tree until at least one tree item
+   exists.
 
 ## Layered architecture
 

package/src/tools/data/Tree/TreeRoot.tsx

@@ -219,6 +219,7 @@ function TreeRootShell<T>({
   // nav, type-ahead, programmatic). Centralised so every focus source gets
   // consistent scrolling — previously only type-ahead scrolled.
   const focusedId = ctx.focused;
+  const isEmpty = ctx.flatRows.length === 0;
   useEffect(() => {
     if (!focusedId) return;
     const el = containerRef.current?.querySelector<HTMLElement>(
@@ -249,11 +250,15 @@ function TreeRootShell<T>({
   const treeBody = (
     <div
       ref={setContainerRef}
-      tabIndex={0}
-      role="tree"
-      aria-label={ctx.labels.ariaLabel}
-      aria-multiselectable={ctx.selectionMode === 'multiple' || undefined}
-      aria-activedescendant={focusedId ? treeRowDomId(focusedId) : undefined}
+      tabIndex={isEmpty ? undefined : 0}
+      role={isEmpty ? undefined : 'tree'}
+      aria-label={isEmpty ? undefined : ctx.labels.ariaLabel}
+      aria-multiselectable={
+        !isEmpty && ctx.selectionMode === 'multiple' ? true : undefined
+      }
+      aria-activedescendant={
+        !isEmpty && focusedId ? treeRowDomId(focusedId) : undefined
+      }
       className={cn(
         'group/tree flex h-full w-full flex-col gap-2 rounded-sm outline-none',
         'focus-visible:ring-1 focus-visible:ring-ring/50',
@@ -264,7 +269,9 @@ function TreeRootShell<T>({
     >
       {enableSearch ? <TreeSearchInput className="mx-2 mt-2" /> : null}
       <div className="flex min-h-0 flex-1 flex-col overflow-auto px-1">
-        <TreeContent<T> role="group">{renderRow}</TreeContent>
+        <TreeContent<T> role={isEmpty ? "presentation" : "group"}>
+          {renderRow}
+        </TreeContent>
         {/* Empty-area: catches right-clicks on whitespace below the
             last row + acts as the root drop target for DnD. Always
             rendered — it self-disables when there's nothing to do. */}

package/src/tools/data/Tree/__tests__/TreeRoot.accessibility.test.tsx

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { TreeRoot } from '../TreeRoot';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('TreeRoot empty semantics', () => {
+  const mounted: Array<ReturnType<typeof createRoot>> = [];
+
+  afterEach(() => {
+    act(() => mounted.splice(0).forEach((root) => root.unmount()));
+  });
+
+  it('announces the empty state without exposing an invalid empty tree', () => {
+    const container = document.createElement('div');
+    const root = createRoot(container);
+    mounted.push(root);
+
+    act(() => {
+      root.render(
+        <TreeRoot<{ name: string }>
+          data={[]}
+          getItemName={(node) => node.data.name}
+        />,
+      );
+    });
+
+    expect(container.querySelector('[role="tree"]')).toBeNull();
+    expect(container.querySelector('[data-tree-root]')?.hasAttribute('tabindex')).toBe(false);
+    expect(container.querySelector('[role="status"]')?.textContent).toBe('Nothing to show');
+  });
+});

package/src/tools/data/Tree/components/TreeEmpty.tsx

@@ -10,6 +10,7 @@ export interface TreeEmptyProps {
 export function TreeEmpty({ children, className }: TreeEmptyProps) {
   return (
     <div
+      role="status"
       className={cn(
         'flex h-full min-h-32 items-center justify-center px-4 py-6 text-sm text-muted-foreground',
         className,