twico-ui 1.4.0 → 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";
@@ -1774,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";
@@ -2279,7 +2286,7 @@ function Page() {
 }
 ```
 
-## Hooks (23)
+## Hooks (25)
 
 ### useIsomorphicLayoutEffect
 
@@ -2323,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
@@ -2358,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
@@ -2366,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
@@ -2438,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
@@ -2446,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
@@ -2465,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.4.0",
+  "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);