@particle-academy/react-fancy 5.72.0 → 6.1.0

package/dist/magic-wand.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkNWB6YCZY_cjs = require('./chunk-NWB6YCZY.cjs');
+var chunkFKZB27OM_cjs = require('./chunk-FKZB27OM.cjs');
 require('./chunk-MAZEX4EZ.cjs');
 require('./chunk-MRZXTL46.cjs');
 require('./chunk-P53432AK.cjs');
@@ -11,9 +11,10 @@ require('./chunk-L3V3BYVS.cjs');
 require('./chunk-MKHYENKR.cjs');
 require('./chunk-TI7D4QDM.cjs');
 require('./chunk-VBWRH4UW.cjs');
-require('./chunk-MOU6O324.cjs');
+require('./chunk-OCHUZ7J3.cjs');
+require('./chunk-X6LGRB4H.cjs');
 require('./chunk-M5MUGSON.cjs');
-require('./chunk-FBGCSGCE.cjs');
+require('./chunk-NZHVDWOM.cjs');
 require('./chunk-XCZZVRBY.cjs');
 require('./chunk-MXWR3T3N.cjs');
 require('./chunk-ZU5Q77OT.cjs');
@@ -22,7 +23,7 @@ require('./chunk-ZU5Q77OT.cjs');
 
 Object.defineProperty(exports, "MagicWand", {
   enumerable: true,
-  get: function () { return chunkNWB6YCZY_cjs.MagicWand; }
+  get: function () { return chunkFKZB27OM_cjs.MagicWand; }
 });
 //# sourceMappingURL=magic-wand.cjs.map
 //# sourceMappingURL=magic-wand.cjs.map

package/dist/magic-wand.js

@@ -1,4 +1,4 @@
-export { MagicWand } from './chunk-B6AIHYOP.js';
+export { MagicWand } from './chunk-F4OYQ2XZ.js';
 import './chunk-UVUBV4VZ.js';
 import './chunk-KXYMMNNV.js';
 import './chunk-WX5XYDVN.js';
@@ -9,9 +9,10 @@ import './chunk-NRXK42LO.js';
 import './chunk-5VMILVWD.js';
 import './chunk-RBCMKPBX.js';
 import './chunk-IQ4KQJAO.js';
-import './chunk-6FCQD2KQ.js';
+import './chunk-OZ4QFJ7N.js';
+import './chunk-S53A6JIE.js';
 import './chunk-LQ4ICCN2.js';
-import './chunk-3KF3OYWS.js';
+import './chunk-4GPH7HOR.js';
 import './chunk-45BBNJQD.js';
 import './chunk-J3A4Z2P7.js';
 import './chunk-MMW2JGKZ.js';

package/dist/prompt-input.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkC2LVHAIG_cjs = require('./chunk-C2LVHAIG.cjs');
+var chunkOUNGGQIS_cjs = require('./chunk-OUNGGQIS.cjs');
 require('./chunk-OASSZI6M.cjs');
 require('./chunk-I27K6NLX.cjs');
 require('./chunk-JKD6CFIP.cjs');
@@ -15,7 +15,7 @@ require('./chunk-TI7D4QDM.cjs');
 require('./chunk-57FQGQJK.cjs');
 require('./chunk-OUYC6EIL.cjs');
 require('./chunk-M5MUGSON.cjs');
-require('./chunk-FBGCSGCE.cjs');
+require('./chunk-NZHVDWOM.cjs');
 require('./chunk-XCZZVRBY.cjs');
 require('./chunk-MXWR3T3N.cjs');
 require('./chunk-SNHU2AI4.cjs');
@@ -25,15 +25,15 @@ require('./chunk-ZU5Q77OT.cjs');
 
 Object.defineProperty(exports, "PromptInput", {
   enumerable: true,
-  get: function () { return chunkC2LVHAIG_cjs.PromptInput; }
+  get: function () { return chunkOUNGGQIS_cjs.PromptInput; }
 });
 Object.defineProperty(exports, "promptDataUrlToFile", {
   enumerable: true,
-  get: function () { return chunkC2LVHAIG_cjs.promptDataUrlToFile; }
+  get: function () { return chunkOUNGGQIS_cjs.promptDataUrlToFile; }
 });
 Object.defineProperty(exports, "promptFileToDataUrl", {
   enumerable: true,
-  get: function () { return chunkC2LVHAIG_cjs.promptFileToDataUrl; }
+  get: function () { return chunkOUNGGQIS_cjs.promptFileToDataUrl; }
 });
 //# sourceMappingURL=prompt-input.cjs.map
 //# sourceMappingURL=prompt-input.cjs.map

package/dist/prompt-input.js

@@ -1,4 +1,4 @@
-export { PromptInput, promptDataUrlToFile, promptFileToDataUrl } from './chunk-TW52N55D.js';
+export { PromptInput, promptDataUrlToFile, promptFileToDataUrl } from './chunk-B6WTCAGY.js';
 import './chunk-GR2WKBER.js';
 import './chunk-SV5BW3IA.js';
 import './chunk-J6IQHJET.js';
@@ -13,7 +13,7 @@ import './chunk-RBCMKPBX.js';
 import './chunk-RGANGU7X.js';
 import './chunk-YX6FTJ6N.js';
 import './chunk-LQ4ICCN2.js';
-import './chunk-3KF3OYWS.js';
+import './chunk-4GPH7HOR.js';
 import './chunk-45BBNJQD.js';
 import './chunk-J3A4Z2P7.js';
 import './chunk-EDYAXGUM.js';

package/dist/reason-tag.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkKDISJ64Q_cjs = require('./chunk-KDISJ64Q.cjs');
+var chunkI2VAGZXY_cjs = require('./chunk-I2VAGZXY.cjs');
 require('./chunk-MKGWHSNV.cjs');
 require('./chunk-J2DI6RMR.cjs');
 require('./chunk-MKHYENKR.cjs');
@@ -8,7 +8,7 @@ require('./chunk-TI7D4QDM.cjs');
 require('./chunk-57FQGQJK.cjs');
 require('./chunk-OUYC6EIL.cjs');
 require('./chunk-M5MUGSON.cjs');
-require('./chunk-FBGCSGCE.cjs');
+require('./chunk-NZHVDWOM.cjs');
 require('./chunk-XCZZVRBY.cjs');
 require('./chunk-MXWR3T3N.cjs');
 require('./chunk-ZU5Q77OT.cjs');
@@ -17,7 +17,7 @@ require('./chunk-ZU5Q77OT.cjs');
 
 Object.defineProperty(exports, "ReasonTag", {
   enumerable: true,
-  get: function () { return chunkKDISJ64Q_cjs.ReasonTag; }
+  get: function () { return chunkI2VAGZXY_cjs.ReasonTag; }
 });
 //# sourceMappingURL=reason-tag.cjs.map
 //# sourceMappingURL=reason-tag.cjs.map

package/dist/reason-tag.js

@@ -1,4 +1,4 @@
-export { ReasonTag } from './chunk-EWE4TOG7.js';
+export { ReasonTag } from './chunk-GSMD5NK5.js';
 import './chunk-QTS4Q2NK.js';
 import './chunk-MQ6VGG62.js';
 import './chunk-5VMILVWD.js';
@@ -6,7 +6,7 @@ import './chunk-RBCMKPBX.js';
 import './chunk-RGANGU7X.js';
 import './chunk-YX6FTJ6N.js';
 import './chunk-LQ4ICCN2.js';
-import './chunk-3KF3OYWS.js';
+import './chunk-4GPH7HOR.js';
 import './chunk-45BBNJQD.js';
 import './chunk-J3A4Z2P7.js';
 import './chunk-MMW2JGKZ.js';

package/dist/sidebar.cjs

@@ -1,12 +1,13 @@
 'use strict';
 
-var chunkEZA6GWZL_cjs = require('./chunk-EZA6GWZL.cjs');
+var chunkGK7IGL7N_cjs = require('./chunk-GK7IGL7N.cjs');
 require('./chunk-A2JUTNE6.cjs');
 require('./chunk-T6YELZPJ.cjs');
 require('./chunk-4GOOSZEK.cjs');
 require('./chunk-TXTRTTG7.cjs');
 require('./chunk-FQZE5N2N.cjs');
 require('./chunk-J2DI6RMR.cjs');
+require('./chunk-X6LGRB4H.cjs');
 require('./chunk-57FQGQJK.cjs');
 require('./chunk-OUYC6EIL.cjs');
 require('./chunk-SNHU2AI4.cjs');
@@ -16,11 +17,11 @@ require('./chunk-ZU5Q77OT.cjs');
 
 Object.defineProperty(exports, "Sidebar", {
   enumerable: true,
-  get: function () { return chunkEZA6GWZL_cjs.Sidebar; }
+  get: function () { return chunkGK7IGL7N_cjs.Sidebar; }
 });
 Object.defineProperty(exports, "useSidebar", {
   enumerable: true,
-  get: function () { return chunkEZA6GWZL_cjs.useSidebar; }
+  get: function () { return chunkGK7IGL7N_cjs.useSidebar; }
 });
 //# sourceMappingURL=sidebar.cjs.map
 //# sourceMappingURL=sidebar.cjs.map

package/dist/sidebar.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { N as NavigableProps } from './types-DJI492iY.cjs';
+import { N as NavigableProps, C as Color } from './types-DJI492iY.cjs';
 
 type SidebarCollapseMode = "icons" | "letters";
 interface SidebarProps {
@@ -29,14 +29,57 @@ interface SidebarProps {
      * @default "icons"
      */
     collapseMode?: SidebarCollapseMode;
+    /**
+     * Wrap the children in `<nav aria-label={navLabel}>`, so the items form a
+     * navigation landmark. The root stays an `<aside>`; the `<nav>` sits inside
+     * it and takes over the column layout. Omitted (or empty), no `<nav>` is
+     * rendered and the markup is exactly what it was before this prop existed.
+     */
+    navLabel?: string;
+    /**
+     * Arrow-key movement between items with a roving tabindex: the rail becomes
+     * ONE tab stop (the active item, else the first enabled one), and
+     * ArrowUp / ArrowDown / Home / End move focus within it. Disabled items and
+     * items inside a closed `Sidebar.Submenu` are skipped; a submenu's trigger
+     * is part of the sequence. Keys pressed in an input, textarea, select or
+     * contenteditable inside the sidebar are never intercepted, and
+     * `Sidebar.Toggle` keeps its own tab stop.
+     *
+     * Opt-in because it changes Tab order: without it every item is its own
+     * tab stop, as before.
+     * @default false
+     */
+    keyboardNav?: boolean;
     className?: string;
 }
+/** Colour of a {@link SidebarItemProps.dot}. `dot={true}` is red. */
+type SidebarDotColor = Color;
 interface SidebarItemProps extends NavigableProps {
     children: ReactNode;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
     badge?: ReactNode;
+    /**
+     * Also render `badge` when the sidebar is collapsed, as an overlay at the
+     * corner of the icon (or of the letters). Off by default: a collapsed rail
+     * has never shown badges, and a wide badge ("Beta") over a 20px icon is not
+     * something to switch on for every existing consumer. Best for short counts.
+     * Handle: `data-react-fancy-sidebar-badge`.
+     */
+    collapsedBadge?: boolean;
+    /**
+     * A small attention dot at the icon's corner (unread, warning, "needs
+     * you"), shown expanded AND collapsed. `true` is red; pass any Badge colour
+     * for another. Purely visual: pair it with `dotLabel`. Handle:
+     * `data-react-fancy-sidebar-dot`, with `data-color`.
+     */
+    dot?: boolean | SidebarDotColor;
+    /**
+     * Screen-reader text for the dot ("3 unread"), rendered visually hidden and
+     * appended to the item's accessible name. Ignored without `dot`.
+     */
+    dotLabel?: string;
     onClick?: () => void;
     className?: string;
 }
@@ -59,9 +102,11 @@ interface SidebarContextValue {
     collapsed: boolean;
     collapseMode: SidebarCollapseMode;
     setCollapsed: (collapsed: boolean) => void;
+    /** Whether the root has `keyboardNav` on. */
+    keyboardNav?: boolean;
 }
 
-declare function SidebarItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: SidebarItemProps): react.JSX.Element;
+declare function SidebarItem({ children, href, as: As, icon, active, disabled, badge, collapsedBadge, dot, dotLabel, onClick, className, ...rest }: SidebarItemProps): react.JSX.Element;
 declare namespace SidebarItem {
     var displayName: string;
 }
@@ -81,7 +126,7 @@ declare namespace SidebarToggle {
     var displayName: string;
 }
 
-declare function SidebarRoot({ children, collapsed: controlledCollapsed, defaultCollapsed, onCollapsedChange, collapseMode, embedded, className, }: SidebarProps): react.JSX.Element;
+declare function SidebarRoot({ children, collapsed: controlledCollapsed, defaultCollapsed, onCollapsedChange, collapseMode, embedded, navLabel, keyboardNav, className, }: SidebarProps): react.JSX.Element;
 declare const Sidebar: typeof SidebarRoot & {
     Item: typeof SidebarItem;
     Group: typeof SidebarGroup;
@@ -91,4 +136,4 @@ declare const Sidebar: typeof SidebarRoot & {
 
 declare function useSidebar(): SidebarContextValue;
 
-export { Sidebar, type SidebarCollapseMode, type SidebarContextValue, type SidebarGroupProps, type SidebarItemProps, type SidebarProps, type SidebarSubmenuProps, type SidebarToggleProps, useSidebar };
+export { Sidebar, type SidebarCollapseMode, type SidebarContextValue, type SidebarDotColor, type SidebarGroupProps, type SidebarItemProps, type SidebarProps, type SidebarSubmenuProps, type SidebarToggleProps, useSidebar };

package/dist/sidebar.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { N as NavigableProps } from './types-DJI492iY.js';
+import { N as NavigableProps, C as Color } from './types-DJI492iY.js';
 
 type SidebarCollapseMode = "icons" | "letters";
 interface SidebarProps {
@@ -29,14 +29,57 @@ interface SidebarProps {
      * @default "icons"
      */
     collapseMode?: SidebarCollapseMode;
+    /**
+     * Wrap the children in `<nav aria-label={navLabel}>`, so the items form a
+     * navigation landmark. The root stays an `<aside>`; the `<nav>` sits inside
+     * it and takes over the column layout. Omitted (or empty), no `<nav>` is
+     * rendered and the markup is exactly what it was before this prop existed.
+     */
+    navLabel?: string;
+    /**
+     * Arrow-key movement between items with a roving tabindex: the rail becomes
+     * ONE tab stop (the active item, else the first enabled one), and
+     * ArrowUp / ArrowDown / Home / End move focus within it. Disabled items and
+     * items inside a closed `Sidebar.Submenu` are skipped; a submenu's trigger
+     * is part of the sequence. Keys pressed in an input, textarea, select or
+     * contenteditable inside the sidebar are never intercepted, and
+     * `Sidebar.Toggle` keeps its own tab stop.
+     *
+     * Opt-in because it changes Tab order: without it every item is its own
+     * tab stop, as before.
+     * @default false
+     */
+    keyboardNav?: boolean;
     className?: string;
 }
+/** Colour of a {@link SidebarItemProps.dot}. `dot={true}` is red. */
+type SidebarDotColor = Color;
 interface SidebarItemProps extends NavigableProps {
     children: ReactNode;
     icon?: ReactNode;
     active?: boolean;
     disabled?: boolean;
     badge?: ReactNode;
+    /**
+     * Also render `badge` when the sidebar is collapsed, as an overlay at the
+     * corner of the icon (or of the letters). Off by default: a collapsed rail
+     * has never shown badges, and a wide badge ("Beta") over a 20px icon is not
+     * something to switch on for every existing consumer. Best for short counts.
+     * Handle: `data-react-fancy-sidebar-badge`.
+     */
+    collapsedBadge?: boolean;
+    /**
+     * A small attention dot at the icon's corner (unread, warning, "needs
+     * you"), shown expanded AND collapsed. `true` is red; pass any Badge colour
+     * for another. Purely visual: pair it with `dotLabel`. Handle:
+     * `data-react-fancy-sidebar-dot`, with `data-color`.
+     */
+    dot?: boolean | SidebarDotColor;
+    /**
+     * Screen-reader text for the dot ("3 unread"), rendered visually hidden and
+     * appended to the item's accessible name. Ignored without `dot`.
+     */
+    dotLabel?: string;
     onClick?: () => void;
     className?: string;
 }
@@ -59,9 +102,11 @@ interface SidebarContextValue {
     collapsed: boolean;
     collapseMode: SidebarCollapseMode;
     setCollapsed: (collapsed: boolean) => void;
+    /** Whether the root has `keyboardNav` on. */
+    keyboardNav?: boolean;
 }
 
-declare function SidebarItem({ children, href, as: As, icon, active, disabled, badge, onClick, className, ...rest }: SidebarItemProps): react.JSX.Element;
+declare function SidebarItem({ children, href, as: As, icon, active, disabled, badge, collapsedBadge, dot, dotLabel, onClick, className, ...rest }: SidebarItemProps): react.JSX.Element;
 declare namespace SidebarItem {
     var displayName: string;
 }
@@ -81,7 +126,7 @@ declare namespace SidebarToggle {
     var displayName: string;
 }
 
-declare function SidebarRoot({ children, collapsed: controlledCollapsed, defaultCollapsed, onCollapsedChange, collapseMode, embedded, className, }: SidebarProps): react.JSX.Element;
+declare function SidebarRoot({ children, collapsed: controlledCollapsed, defaultCollapsed, onCollapsedChange, collapseMode, embedded, navLabel, keyboardNav, className, }: SidebarProps): react.JSX.Element;
 declare const Sidebar: typeof SidebarRoot & {
     Item: typeof SidebarItem;
     Group: typeof SidebarGroup;
@@ -91,4 +136,4 @@ declare const Sidebar: typeof SidebarRoot & {
 
 declare function useSidebar(): SidebarContextValue;
 
-export { Sidebar, type SidebarCollapseMode, type SidebarContextValue, type SidebarGroupProps, type SidebarItemProps, type SidebarProps, type SidebarSubmenuProps, type SidebarToggleProps, useSidebar };
+export { Sidebar, type SidebarCollapseMode, type SidebarContextValue, type SidebarDotColor, type SidebarGroupProps, type SidebarItemProps, type SidebarProps, type SidebarSubmenuProps, type SidebarToggleProps, useSidebar };

package/dist/sidebar.js

@@ -1,10 +1,11 @@
-export { Sidebar, useSidebar } from './chunk-YJHP5FVA.js';
+export { Sidebar, useSidebar } from './chunk-MTDOFZIB.js';
 import './chunk-2BXMMVQS.js';
 import './chunk-CPY7NHXM.js';
 import './chunk-ZQ3VXRUY.js';
 import './chunk-5U2DZ7AV.js';
 import './chunk-3K2CEAI7.js';
 import './chunk-MQ6VGG62.js';
+import './chunk-S53A6JIE.js';
 import './chunk-RGANGU7X.js';
 import './chunk-YX6FTJ6N.js';
 import './chunk-EDYAXGUM.js';

package/dist/toast.cjs

@@ -1,10 +1,11 @@
 'use strict';
 
-var chunkH2YRZYKK_cjs = require('./chunk-H2YRZYKK.cjs');
+var chunkKFA7B6WP_cjs = require('./chunk-KFA7B6WP.cjs');
 require('./chunk-MKHYENKR.cjs');
 require('./chunk-TI7D4QDM.cjs');
 require('./chunk-VBWRH4UW.cjs');
-require('./chunk-MOU6O324.cjs');
+require('./chunk-OCHUZ7J3.cjs');
+require('./chunk-X6LGRB4H.cjs');
 require('./chunk-SNHU2AI4.cjs');
 require('./chunk-ZU5Q77OT.cjs');
 
@@ -12,11 +13,11 @@ require('./chunk-ZU5Q77OT.cjs');
 
 Object.defineProperty(exports, "Toast", {
   enumerable: true,
-  get: function () { return chunkH2YRZYKK_cjs.Toast; }
+  get: function () { return chunkKFA7B6WP_cjs.Toast; }
 });
 Object.defineProperty(exports, "useToast", {
   enumerable: true,
-  get: function () { return chunkH2YRZYKK_cjs.useToast; }
+  get: function () { return chunkKFA7B6WP_cjs.useToast; }
 });
 //# sourceMappingURL=toast.cjs.map
 //# sourceMappingURL=toast.cjs.map

package/dist/toast.js

@@ -1,8 +1,9 @@
-export { Toast, useToast } from './chunk-BQFPC5FL.js';
+export { Toast, useToast } from './chunk-ESCIXKFT.js';
 import './chunk-5VMILVWD.js';
 import './chunk-RBCMKPBX.js';
 import './chunk-IQ4KQJAO.js';
-import './chunk-6FCQD2KQ.js';
+import './chunk-OZ4QFJ7N.js';
+import './chunk-S53A6JIE.js';
 import './chunk-EDYAXGUM.js';
 import './chunk-MMW2JGKZ.js';
 //# sourceMappingURL=toast.js.map

package/docs/Button.md

@@ -44,6 +44,7 @@ import { Button } from "@particle-academy/react-fancy";
 | sort | `string` | `"eiab"` | Sort order of decorative elements: `e`=emoji, `i`=icon, `a`=avatar, `b`=badge |
 | loading | `boolean` | `false` | Show loading spinner (disables the button) |
 | disabled | `boolean` | - | Disable the button |
+| type | `"button" \| "submit" \| "reset"` | `"button"` | Native button type. **Defaults to `"button"` since 6.0.0** (it was the HTML default, `submit`, before), so a Button inside a `<form>` does not submit it unless you pass `type="submit"`. Not applied in anchor mode. |
 | href | `string` | - | Render as an anchor tag instead of a button. Sanitized to a safe-protocol allow-list (since v2.5.0) — `javascript:`, `data:`, `vbscript:` are silently dropped and the component renders a `<button>` instead of an `<a>`. |
 
 Also extends all native `<button>` HTML attributes (except `color`).
@@ -75,6 +76,18 @@ Also extends all native `<button>` HTML attributes (except `color`).
 </Button>
 ```
 
+### In a form
+
+A Button is `type="button"` unless you say otherwise, so only the one that
+should submit says so:
+
+```tsx
+<form onSubmit={save}>
+  <Button type="button" variant="ghost" onClick={cancel}>Cancel</Button>
+  <Button type="submit" color="blue">Save</Button>
+</form>
+```
+
 ### Link button with trailing icon
 
 ```tsx
@@ -89,3 +102,11 @@ Also extends all native `<button>` HTML attributes (except `color`).
 <Button variant="ghost" color="red" icon="trash-2">Delete</Button>
 <Button variant="ghost" icon="download">Export</Button>
 ```
+
+## Focus ring
+
+The ring shows on `:focus-visible` only, so it appears when someone reaches the
+Button by keyboard and not after a mouse click. It uses the focus token
+(`--fancy-focus`, blue-500 by default; `--fancy-focus-dark`, blue-400, in dark
+mode) and is offset against the surface token, so dark mode gets no white gap.
+Override it with `focus-visible:ring-*` classes in `className`.

package/docs/Sidebar.md

@@ -34,6 +34,9 @@ import { Sidebar, Icon } from "@particle-academy/react-fancy";
 | defaultCollapsed | `boolean` | `false` | Default collapsed state (uncontrolled) |
 | onCollapsedChange | `(collapsed: boolean) => void` | - | Callback when collapsed state changes |
 | collapseMode | `"icons" \| "letters"` | `"icons"` | How items display when collapsed: icons only, or first 3 letters |
+| embedded | `boolean` | `false` | Drop the app-shell chrome (right border, background, fixed `w-60`) for a sidebar inside a card, panel or drawer |
+| navLabel | `string` | - | Wrap the children in `<nav aria-label={navLabel}>` so the items form a navigation landmark. Omitted, no `<nav>` is rendered |
+| keyboardNav | `boolean` | `false` | ArrowUp / ArrowDown / Home / End between items, with a roving tabindex (the rail becomes one tab stop). See [Keyboard navigation](#keyboard-navigation) |
 | className | `string` | - | Additional CSS classes |
 
 ### Sidebar.Item
@@ -45,7 +48,10 @@ import { Sidebar, Icon } from "@particle-academy/react-fancy";
 | icon | `ReactNode` | - | Leading icon |
 | active | `boolean` | - | Active state highlight |
 | disabled | `boolean` | - | Disable the item |
-| badge | `ReactNode` | - | Trailing badge element |
+| badge | `ReactNode` | - | Trailing badge element (expanded only, unless `collapsedBadge`) |
+| collapsedBadge | `boolean` | `false` | Also show `badge` on a collapsed rail, as an overlay at the icon's corner. Best for short counts |
+| dot | `boolean \| Color` | - | Attention dot at the icon's corner, shown expanded and collapsed. `true` is red; any Badge colour otherwise |
+| dotLabel | `string` | - | Screen-reader text for the dot ("3 unread"), visually hidden and added to the item's accessible name |
 | onClick | `() => void` | - | Click handler |
 | className | `string` | - | Additional CSS classes |
 
@@ -94,6 +100,74 @@ const [collapsed, setCollapsed] = useState(false);
 - `"icons"` (default) — only the icon is shown when collapsed; falls back to the first 3 letters if no icon is provided
 - `"letters"` — the first 3 letters of the label are always shown
 
+## Attention marks on a compact rail
+
+A collapsed rail shows only icons, so `badge` is hidden there by default. Use
+`dot` for an unread, warning or "needs you" mark: it renders at the icon's
+corner in both modes. A dot is only colour, so give it a `dotLabel` for screen
+readers.
+
+```tsx
+<Sidebar collapsed navLabel="Main">
+  <Sidebar.Item icon={<Icon name="inbox" size="sm" />} dot dotLabel="3 unread">
+    Inbox
+  </Sidebar.Item>
+  <Sidebar.Item icon={<Icon name="triangle-alert" size="sm" />} dot="amber" dotLabel="needs you">
+    Deploys
+  </Sidebar.Item>
+  <Sidebar.Item
+    icon={<Icon name="message-square" size="sm" />}
+    badge={<Badge size="sm" color="blue" variant="solid">12</Badge>}
+    collapsedBadge
+  >
+    Messages
+  </Sidebar.Item>
+</Sidebar>
+```
+
+- The collapsed item is still named by its label (`title` and a visually
+  hidden copy of the label), so the dot label or a badge count never replaces
+  the name: a screen reader hears "Inbox 3 unread".
+- With both `dot` and `collapsedBadge` on a collapsed item, the badge takes the
+  top corner and the dot moves to the bottom one (`data-position="bottom"`).
+- Handles: `data-react-fancy-sidebar-dot` (with `data-color` and
+  `data-position`), `data-react-fancy-sidebar-dot-label`,
+  `data-react-fancy-sidebar-badge` for the collapsed badge overlay.
+
+## Navigation landmark
+
+`Sidebar` renders an `<aside>`. Pass `navLabel` to wrap its children in a
+labelled `<nav>`, so the items appear in a screen reader's landmark list:
+
+```tsx
+<Sidebar navLabel="Main">…</Sidebar>
+```
+
+The `<nav>` (`data-react-fancy-sidebar-nav`) takes over the column layout and
+fills the rail, so a footer pushed down with `mt-auto` still reaches the
+bottom. Without `navLabel` the markup is unchanged.
+
+## Keyboard navigation
+
+`keyboardNav` turns the rail into one tab stop with a roving tabindex:
+
+- **Tab** lands on the active item (the one with `active`), or the first
+  enabled item when none is active. `Sidebar.Toggle` keeps its own tab stop.
+- **ArrowDown / ArrowUp** move to the next / previous item; **Home / End** to
+  the first / last. No wrap at the ends.
+- Disabled items are skipped. An open `Sidebar.Submenu`'s trigger and its items
+  are in the sequence; a closed submenu's items are skipped (its trigger gets
+  `aria-expanded`). Enter / Space on a trigger opens it as usual.
+- Keys pressed in an input, textarea, select or contenteditable inside the
+  sidebar are never intercepted, nor are arrows with a modifier key.
+
+It is opt-in because it changes Tab order: without it, every item is its own
+tab stop, exactly as before.
+
+```tsx
+<Sidebar keyboardNav navLabel="Main">…</Sidebar>
+```
+
 ## useSidebar Hook
 
 Access collapsed state from any child component:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "5.72.0",
+  "version": "6.1.0",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",