twico-ui 1.3.2 → 1.5.0

package/llms.txt

@@ -291,6 +291,8 @@ Props:
 - `children` — `React.ReactNode` — Main content; fills the remaining space and scrolls independently of the fixed sidebar and header.
 - `height` — `string | number` · default `"100dvh"` — Overall shell height; pass a fixed value to embed the shell inside a smaller region (e.g. a demo).
 - `padded` — `boolean` · default `true` — Pads the scrollable content region with the standard page padding; set false for edge-to-edge content.
+- `sidebarOpen` — `boolean` — Open state of the sidebar's off-canvas drawer on mobile; providing this (or onSidebarOpenChange) makes the shell forward overlay/open/onOpenChange to the sidebar element.
+- `onSidebarOpenChange` — `(open: boolean) => void` — Called when the sidebar drawer requests open or close; wire a Navbar's onMenuClick to () => onSidebarOpenChange(true) for the mobile menu button.
 
 ```jsx
 import { AppShell, Sidebar, Button } from "twico-ui";
@@ -1330,14 +1332,16 @@ Props:
 - `rowKey` — `(row,index)=>key` · default `(r,i)=>r.id??i` — Returns a stable unique key per row, defaulting to the row's id or its index, to keep selection and renders consistent.
 - `checkboxSelection` — `boolean` · default `false` — Adds a leading checkbox column for selecting rows, enabling batch actions; off by default.
 - `batchActions` — `DatatableBatchAction array` · default `[]` — Defines actions shown in the selection toolbar that operate on the currently selected rows; empty by default.
-- `density` — `compact|standard|comfortable` · default `standard` — Sets the row height preset (compact, standard, or comfortable) to trade vertical space for readability, defaulting to standard.
+- `density` — `compact|standard|comfortable` · default `comfortable` — Sets the row height preset (compact, standard, or comfortable) to trade vertical space for readability, defaulting to comfortable.
 - `pageSize` — `number` · default `10` — Sets the initial number of rows shown per page, defaulting to 10; pass 0 to disable pagination.
 - `pageSizeOptions` — `number array` · default `[5,10,25,50]` — Lists the selectable rows-per-page values offered in the pagination control, defaulting to [5,10,25,50].
 - `height` — `number` · default `440` — Sets the maximum scroll height of the grid body in pixels before rows scroll internally, defaulting to 440.
 - `serverMode` — `boolean` · default `false` — Switches to server-side data handling so sorting, filtering, and paging are delegated to your backend; off by default.
 - `rowCount` — `number` · default `-` — Tells the grid the total number of server-side rows so pagination can render correctly in serverMode.
 - `onServerChange` — `(state)=>void` · default `-` — Fires with the current query state (sort, filter, page) in serverMode so you can fetch the matching rows.
-- `showExport` — `boolean` · default `true` — Shows the toolbar Export button for downloading data in supported formats; enabled by default.
+- `showExport` — `boolean` · default `false` — Shows the toolbar Export button (CSV split button with a format menu); hidden by default — enable it to expose exporting.
+- `showDensity` — `boolean` · default `false` — Shows the toolbar density button that cycles compact/standard/comfortable; hidden by default (the density prop still sets the row height).
+- `showPivot` — `boolean` · default `false` — Shows the toolbar Pivot button; hidden by default, but appears automatically when a pivot model or pivotMode is provided.
 - `exportFilename` — `string` · default `export` — Sets the base filename used for exported files, defaulting to "export".
 - `aggregationValues` — `object|null` · default `null` — Supplies precomputed footer aggregation values for serverMode, where totals cannot be calculated client-side; null by default.
 - `disableColumnReorder` — `boolean` · default `false` — Prevents users from dragging columns into a new order, locking the column arrangement; off by default.
@@ -1351,7 +1355,7 @@ Props:
 - `onRowClick` — `(row,key)=>void` · default `-` — Fires with the clicked row and its key, useful for navigation or opening a detail view.
 - `onCellClick` — `(value,row,field)=>void` · default `-` — Fires with the clicked cell's value, its row, and the field name when a cell is clicked.
 - `onActiveCellChange` — `(cell|null)=>void` · default `-` — Fires when the active cell changes via keyboard or click, receiving the new cell descriptor or null.
-- `showAggregation` — `boolean` · default `false` — Shows a totals row with column aggregations beneath the data on initial render; off by default.
+- `showAggregation` — `boolean` · default `false` — Shows the toolbar Aggregation button and starts with the totals row on; hidden by default, so enable it to expose column aggregations.
 - `ariaLabel` — `string` · default `Data table` — Sets the grid's accessible aria-label for screen readers, defaulting to "Data table".
 - `rowGrouping` — `string array` · default `[]` — Lists the field names to group rows by on initial render, collapsing rows into expandable groups; empty by default.
 - `rowPinning` — `boolean` · default `false` — Allows users to pin rows to the top or bottom so they stay visible while scrolling; off by default.
@@ -1453,6 +1457,8 @@ export default function Example() {
       onRowUpdate={(updated) => setRows((d) => d.map((r) => (r.id === updated.id ? updated : r)))}
       onBatchUpdate={(changed) => setRows((d) => d.map((r) => changed.find((c) => c.id === r.id) || r))}
       showAggregation
+      showDensity
+      showExport
       rowPinning
       pageSize={10}
     />
@@ -1770,6 +1776,11 @@ Props:
 - `defaultCollapsed` — `boolean` · default `false` — Initial collapsed state for uncontrolled usage, defaulting to false so the sidebar starts fully expanded.
 - `collapsible` — `boolean` · default `true` — Shows the collapse toggle button when true (the default), allowing users to switch to the icon-only rail.
 - `onCollapsedChange` — `(collapsed: boolean) => void` — Fires with the new boolean state whenever the collapse toggle is activated, useful for persisting the preference.
+- `overlay` — `boolean` · default `false` — Renders the sidebar as an off-canvas drawer instead of an in-flow rail: a fixed slide-over panel behind a dismissable backdrop, portaled to the body, with a focus trap, Escape-to-close, and scroll lock.
+- `open` — `boolean` — Controlled open state of the overlay drawer (only meaningful when overlay is set); the parent owns visibility.
+- `defaultOpen` — `boolean` · default `false` — Initial open state of the overlay drawer for uncontrolled usage, defaulting to closed.
+- `onOpenChange` — `(open: boolean) => void` — Fires when the overlay drawer requests open or close (backdrop click or Escape); wire it to your open state.
+- `navLabel` — `string` · default `"Main"` — Accessible name for the inner nav landmark and the overlay dialog, so assistive tech can distinguish multiple navigations.
 
 ```jsx
 import { Sidebar } from "twico-ui";
@@ -2275,7 +2286,7 @@ function Page() {
 }
 ```
 
-## Hooks (23)
+## Hooks (25)
 
 ### useIsomorphicLayoutEffect
 
@@ -2319,18 +2330,18 @@ export function useDisclosure(initial?: boolean): { open: boolean; onOpen: () =>
 
 ### useControllableState
 
-Controlled/uncontrolled state — the pattern every form component needs.
+Controlled/uncontrolled state — the pattern every form component needs. Returns `[value, setValue, isControlled]`; the third element reports whether a `value` prop is currently driving the state. In development it warns once if a component switches between controlled and uncontrolled.
 
 ```ts
-export function useControllableState<T>(options?: { value?: T; defaultValue?: T; onChange?: (value: T) => void; }): [T, (next: T | ((prev: T) => T)) => void];
+export function useControllableState<T>(options?: { value?: T; defaultValue?: T; onChange?: (value: T) => void; }): [T, (next: T | ((prev: T) => T)) => void, boolean];
 ```
 
 ### useMediaQuery
 
-Reactively match a media query (SSR-safe).
+Reactively match a media query. Returns `defaultValue` on the server and the first client render, then syncs after mount — so hydration never mismatches.
 
 ```ts
-export function useMediaQuery(query: string): boolean;
+export function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;
 ```
 
 ### usePrefersReducedMotion
@@ -2354,7 +2365,7 @@ export function useColorScheme(options?: UseColorSchemeOptions): { theme: "light
 Attach an event listener (window by default, or a ref/element) with cleanup.
 
 ```ts
-export function useEventListener( eventName: string, handler: (event: any) => void, element?: React.RefObject<any> | EventTarget | null, options?: boolean | AddEventListenerOptions ): void;
+export function useEventListener( eventName: string, handler: (event: any) => void, element?: React.RefObject<any | null> | EventTarget | null, options?: boolean | AddEventListenerOptions ): void;
 ```
 
 ### useClickOutside
@@ -2362,7 +2373,7 @@ export function useEventListener( eventName: string, handler: (event: any) => vo
 Call `handler` when a pointer/touch event lands outside `ref`.
 
 ```ts
-export function useClickOutside<T extends HTMLElement = HTMLElement>( ref: React.RefObject<T>, handler: (event: Event) => void, events?: string[] ): void;
+export function useClickOutside<T extends HTMLElement = HTMLElement>( ref: React.RefObject<T | null>, handler: (event: Event) => void, events?: string[] ): void;
 ```
 
 ### useKeyPress
@@ -2434,7 +2445,7 @@ export function useWindowSize(): { width: number; height: number };
 `true` while the pointer is over the element referenced by `ref`.
 
 ```ts
-export function useHover<T extends HTMLElement = HTMLElement>(ref: React.RefObject<T>): boolean;
+export function useHover<T extends HTMLElement = HTMLElement>(ref: React.RefObject<T | null>): boolean;
 ```
 
 ### useIntersectionObserver
@@ -2442,7 +2453,7 @@ export function useHover<T extends HTMLElement = HTMLElement>(ref: React.RefObje
 The latest IntersectionObserver entry for the element referenced by `ref`.
 
 ```ts
-export function useIntersectionObserver<T extends HTMLElement = HTMLElement>( ref: React.RefObject<T>, options?: IntersectionObserverInit ): IntersectionObserverEntry | null;
+export function useIntersectionObserver<T extends HTMLElement = HTMLElement>( ref: React.RefObject<T | null>, options?: IntersectionObserverInit ): IntersectionObserverEntry | null;
 ```
 
 ### useScrollLock
@@ -2461,6 +2472,22 @@ A stable, SSR-safe unique id (optionally prefixed).
 export function useId(prefix?: string): string;
 ```
 
+### useFocusTrap
+
+Trap focus inside the modal region referenced by `ref`. While `active`, focus moves inside on activate, Tab/Shift+Tab cycle within it, and (by default) focus is restored to the previously-focused element on deactivate. Escape is NOT handled — that stays with the component. SSR-safe.
+
+```ts
+export function useFocusTrap<T extends HTMLElement = HTMLElement>( ref: React.RefObject<T | null>, active?: boolean, options?: UseFocusTrapOptions ): void;
+```
+
+### usePortal
+
+Returns a stable `render(node)` that portals `node` to `document.body`, or `null` on the server (no document). Centralizes the overlay portal pattern.
+
+```ts
+export function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
+```
+
 ---
 
 _Generated by `scripts/gen-llms.mjs`. Do not edit by hand — run `npm run gen:llms`. Source of truth: the component `.d.ts` files and `hooks/index.d.ts`._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twico-ui",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Twico UI — a free, modern, themeable React + Tailwind-friendly component library. 61 components with dark mode, motion, and accessibility built in.",
   "license": "MIT",
   "author": "Twico UI",
@@ -82,6 +82,8 @@
     "gen:llms:check": "node scripts/gen-llms.mjs --check",
     "typecheck": "tsc --noEmit",
     "check:exports": "attw --pack . --profile node16 --exclude-entrypoints styles.css",
+    "gen:ds-bundle": "node scripts/gen-ds-bundle.mjs",
+    "check:ds-bundle": "node scripts/check-ds-bundle.mjs",
     "test": "vitest",
     "test:run": "vitest run",
     "size": "size-limit",

package/styles/twico-ui.css

@@ -169,8 +169,9 @@
   --color-primary-subtle-fg:   var(--brand-700);
   --color-primary-border:      var(--brand-200);
 
-  /* Focus ring */
-  --color-ring: rgb(99 102 241 / 0.45);
+  /* Focus ring — solid brand so the 3px ring clears WCAG 2.4.11 / 1.4.11 (3:1)
+     on light surfaces (a translucent indigo alpha-composited to only ~1.8:1). */
+  --color-ring: var(--brand-500);
 
   /* Success */
   --color-success:        var(--emerald-600);
@@ -180,7 +181,7 @@
 
   /* Warning */
   --color-warning:        var(--amber-500);
-  --color-warning-fg:     #ffffff;
+  --color-warning-fg:     var(--amber-950); /* dark ink on amber-500 = 6.97:1 (white was 2.15:1) */
   --color-warning-subtle:    var(--amber-50);
   --color-warning-subtle-fg: var(--amber-600);
 
@@ -193,7 +194,7 @@
 
   /* Info */
   --color-info:           var(--sky-500);
-  --color-info-fg:        #ffffff;
+  --color-info-fg:        var(--sky-950); /* dark ink on sky-500 (white was 2.77:1) */
   --color-info-subtle:       var(--sky-50);
   --color-info-subtle-fg:    var(--sky-600);
 }
@@ -229,7 +230,7 @@
   --color-primary-subtle-fg:   var(--brand-300);
   --color-primary-border:      rgb(99 102 241 / 0.35);
 
-  --color-ring: rgb(129 140 248 / 0.55);
+  --color-ring: var(--brand-400); /* solid brand-400 ≈ 5.7:1 on slate-900 (translucent was ~2.7:1) */
 
   --color-success:        var(--emerald-500);
   --color-success-fg:     #052e1d;
@@ -564,6 +565,15 @@ textarea:focus-visible,
 select:focus-visible {
   box-shadow: none;
 }
+/* Windows High Contrast / forced-colors strips author box-shadows, which would
+   erase the box-shadow focus ring entirely. Repaint a real outline in the user's
+   system palette (CanvasText) — the designed ring is untouched in normal render. */
+@media (forced-colors: active) {
+  :focus-visible {
+    outline: 2px solid CanvasText;
+    outline-offset: 2px;
+  }
+}
 
 ::selection {
   background: var(--color-primary-subtle);