@kenos-ui/react-datepicker 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @kenos-ui/react-datepicker
 
+## 0.4.0
+
+### Minor Changes
+
+- docs(readme): major update to README
+  - Document the unified `DatePicker.Root` + `mode` API correctly
+  - Highlight the segmented `<DatePicker.Input />` as the main feature
+  - Add clear examples for range (dual inputs + hover preview), multiple, and full composition
+  - Improve props, localization and advanced Content sections
+
+## 0.3.3
+
+### Patch Changes
+
+- docs: major refresh of README.md and root documentation
+  - Update package README to accurately reflect current API (unified `DatePicker.Root` with `mode`, first-class `<DatePicker.Input>`, full composition)
+  - Add strong examples for segmented input, range with dual inputs + hover preview, multiple selection, and custom rendering
+  - Align with brand voice and recent announcement content
+  - Update root README with correct features and examples
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [aaa8a57]
+  - @kenos-ui/utils@0.0.1
+
 ## 0.3.1
 
 ### Patch Changes
@@ -11,7 +38,6 @@
 ### Minor Changes
 
 - Axis lift-and-shift: publish DatePicker under `@at5/axis-datepicker`.
-
   - Add `@at5/axis-datepicker` — same DatePicker API and behavior as `@at5/kairo` (migrated from `packages/kairo` to `packages/datepicker`)
   - Add `@at5/axis` — aggregator re-exporting `DatePicker`
   - `@at5/kairo` — deprecated; thin re-export of `@at5/axis-datepicker` for transition

package/README.md

@@ -1,16 +1,14 @@
 # @kenos-ui/react-datepicker
 
-Kenos UI — headless date & scheduling primitives for React. Built on top of the native `Intl` API, timescape and Floating UI — with full keyboard navigation and WAI-ARIA compliance.
+Headless date & scheduling primitives for React.
 
-## Features
+Built on native `Intl`, [timescape](https://github.com/dan-lee/timescape) (segmented inputs), and Floating UI. Full keyboard navigation, WAI-ARIA patterns, and a focus on real-world composition.
 
-- **Calendar** — WAI-ARIA grid pattern with roving focus and full keyboard navigation
-- **Date Picker** — Input + popover calendar, semantic HTML only
-- **Date Range Picker** — Dual-endpoint selection with live hover preview and optional presets
-- **Date Field** — Segmented spinbutton input (day/month/year), no calendar required
-- Locale-aware: respects week start day, date format order, and RTL scripts
-- Unstyled — bring your own CSS
-- React 19+, TypeScript-first
+- Single, range, and multiple selection with one API (`mode`)
+- Outstanding segmented date input (`<DatePicker.Input />`)
+- Fully unstyled — bring your own CSS or Tailwind
+- Excellent keyboard + screen reader support
+- React 19+ and TypeScript-first
 
 ## Installation
 
@@ -18,15 +16,21 @@ Kenos UI — headless date & scheduling primitives for React. Built on top of th
 npm install @kenos-ui/react-datepicker
 ```
 
-## Quick Start
+## Quick start (with segmented input)
 
 ```tsx
 import { DatePicker } from "@kenos-ui/react-datepicker";
 
 function App() {
+  const [date, setDate] = useState<Date | null>(null);
+
   return (
-    <DatePicker.Root>
-      <DatePicker.Trigger>Pick a date</DatePicker.Trigger>
+    <DatePicker.Root value={date} onValueChange={setDate}>
+      <DatePicker.Label>Pick a date</DatePicker.Label>
+      <div>
+        <DatePicker.Input />
+        <DatePicker.Trigger>📅</DatePicker.Trigger>
+      </div>
       <DatePicker.Content>
         <DatePicker.Calendar />
       </DatePicker.Content>
@@ -35,125 +39,146 @@ function App() {
 }
 ```
 
-## Components
+The `<DatePicker.Input />` gives users a native-feeling segmented editor (month / day / year) that respects the locale's order and separators.
 
-### Calendar
+## Date range
 
-Standalone month grid (composed via DatePicker.Root + calendar parts for full control, or the shorthand).
+One of the strongest use cases:
 
 ```tsx
-import { DatePicker } from "@kenos-ui/react-datepicker";
+import { DatePicker, type DateRange } from "@kenos-ui/react-datepicker";
 
-<DatePicker.Root locale="en-US" onValueChange={(date) => console.log(date)}>
-  <DatePicker.ViewControl>
-    <DatePicker.PrevTrigger />
-    <DatePicker.ViewTrigger />
-    <DatePicker.NextTrigger />
-  </DatePicker.ViewControl>
-  <DatePicker.View view="day">
-    <DatePicker.Grid header={<DatePicker.WeekDays />}>
-      {({ weeks }) => weeks.map((week, i) => (
-        <tr key={i}>
-          {week.map((d, j) => <DatePicker.Day key={j} date={d} />)}
-        </tr>
-      ))}
-    </DatePicker.Grid>
-  </DatePicker.View>
-</DatePicker.Root>
+function TripDates() {
+  const [range, setRange] = useState<DateRange>({ start: null, end: null });
 
-// Or shorthand inside a Root:
-<DatePicker.Root>
-  <DatePicker.Calendar />
-</DatePicker.Root>
+  return (
+    <DatePicker.Root mode="range" value={range} onValueChange={setRange}>
+      <DatePicker.Label>Trip dates</DatePicker.Label>
+      <div>
+        <DatePicker.Input index={0} />
+        <span>to</span>
+        <DatePicker.Input index={1} />
+        <DatePicker.Trigger>📅</DatePicker.Trigger>
+      </div>
+      <DatePicker.Content>
+        <DatePicker.Calendar />
+      </DatePicker.Content>
+    </DatePicker.Root>
+  );
+}
 ```
 
-**Props on Root:** `value`, `defaultValue`, `onValueChange`, `locale`, `weekStartsOn`, `minDate`, `maxDate`, `disabled`, `mode`
-
-**Data attributes (on Day):** `[data-selected]`, `[data-today]`, `[data-outside-month]`, `[data-disabled]`, `[data-in-range]`, `[data-range-start]`, `[data-range-end]`
+Range mode includes live hover preview between start and end.
 
-For the dedicated "Date Field" experience use a minimal Root + Input only.
-
----
-
-### Date Picker
-
-Text input paired with a calendar popover.
+## Multiple dates
 
 ```tsx
-import { DatePicker } from "@kenos-ui/react-datepicker";
-
-<DatePicker.Root locale="en-US" onValueChange={(date) => console.log(date)}>
+<DatePicker.Root mode="multiple" onValueChange={setDates}>
+  <DatePicker.Input />
   <DatePicker.Trigger />
   <DatePicker.Content>
     <DatePicker.Calendar />
   </DatePicker.Content>
-</DatePicker.Root>;
+</DatePicker.Root>
 ```
 
-**Props:** `value`, `defaultValue`, `onValueChange`, `open`, `onOpenChange`, `locale`, `format`, `closeOnSelect`, `placement`
+## Calendar composition
 
-**Keyboard:** `Enter`/`Space` opens popover, `Escape` closes, arrow keys navigate calendar.
-
----
+Use the convenient shorthand:
 
-### Date Range Picker
+```tsx
+<DatePicker.Root>
+  <DatePicker.Calendar />
+</DatePicker.Root>
+```
 
-Selects a start and end date with optional night presets.
+Or take full control:
 
 ```tsx
-import { DateRangePicker } from "@kenos-ui/react-datepicker";
-
-<DateRangePicker.Root locale="en-US" onValueChange={({ start, end }) => console.log(start, end)}>
-  <DateRangePicker.Trigger />
-  <DateRangePicker.Content>
-    <DateRangePicker.Calendar />
-  </DateRangePicker.Content>
-</DateRangePicker.Root>;
+<DatePicker.Root>
+  <DatePicker.ViewControl>
+    <DatePicker.PrevTrigger />
+    <DatePicker.ViewTrigger />
+    <DatePicker.NextTrigger />
+  </DatePicker.ViewControl>
+
+  <DatePicker.View view="day">
+    <DatePicker.Grid header={<DatePicker.WeekDays />}>
+      {({ weeks }) =>
+        weeks.map((week, i) => (
+          <tr key={i}>
+            {week.map((d, j) => (
+              <DatePicker.Day key={j} date={d}>
+                {({ isSelected, isToday }) => (
+                  // custom rendering
+                  <span className={isSelected ? "selected" : ""}>{d.getDate()}</span>
+                )}
+              </DatePicker.Day>
+            ))}
+          </tr>
+        ))
+      }
+    </DatePicker.Grid>
+  </DatePicker.View>
+</DatePicker.Root>
 ```
 
-**Props:** `value`, `defaultValue`, `onValueChange`, `minNights`, `maxNights`, `presets`, `locale`
+You can also render month/year grids with `MonthGrid` / `YearGrid`.
 
----
+## Positioning & advanced Content
 
-### Date Field
+`<DatePicker.Content>` is powered by Floating UI and supports:
 
-Segmented spinbutton input — no popover, locale-aware segment order.
+- `side`, `align`, `sideOffset`, `alignOffset`
+- `portal`
+- `forceMount` (for enter/exit animations via `[data-state="open"]`)
+- `avoidCollisions`
 
 ```tsx
-import { DateField } from "@kenos-ui/react-datepicker";
-
-<DateField.Root locale="en-US" onValueChange={(date) => console.log(date)}>
-  <DateField.Segment segment="month" />
-  <DateField.Literal>/</DateField.Literal>
-  <DateField.Segment segment="day" />
-  <DateField.Literal>/</DateField.Literal>
-  <DateField.Segment segment="year" />
-</DateField.Root>;
+<DatePicker.Content portal side="top" align="end" forceMount>
+  <DatePicker.Calendar />
+</DatePicker.Content>
 ```
 
-**Props:** `value`, `defaultValue`, `onValueChange`, `locale`, `granularity`, `min`, `max`
+## Key props on Root
+
+- `mode`: `"single" | "range" | "multiple"`
+- `locale`, `weekStartsOn`
+- `minDate`, `maxDate`, `disabled`
+- `readOnly`
+- `modal` — opt-in focus trap + `aria-modal` (default `false` — follows popup policy)
+- `defaultOpen`, `closeOnSelect`
 
-**Keyboard:** `↑`/`↓` increments/decrements the focused segment, `Tab` advances to next segment.
+See the full prop tables and more examples in the [project README](https://github.com/allysontsoares/kenos-ui/blob/main/README.md).
 
 ## Localization
 
-All components accept a `locale` prop compatible with `Intl.Locale`. Week start day, month/day/year order, and calendar display adapt automatically.
+Everything is driven by `Intl.Locale`:
 
 ```tsx
-// Arabic RTL
-<DatePicker.Root locale="ar" />
-
-// Brazilian Portuguese
-<DatePicker.Root locale="pt-BR" />
-
-// Japanese
+<DatePicker.Root locale="pt-BR" />   {/* dd/mm/yyyy, week starts Monday */}
+<DatePicker.Root locale="ar" />      {/* RTL + Saturday start */}
 <DatePicker.Root locale="ja-JP" />
 ```
 
 ## Requirements
 
-- React `>=19.0.0`
-- Node.js `>=22`
+- React ≥ 19
+- Node ≥ 22
+
+## Exports
+
+```ts
+import {
+  DatePicker,
+  useDatePickerContext,
+  // types
+  type DatePickerRootProps,
+  type DateRange,
+  type DayCellMeta,
+  // ...
+} from "@kenos-ui/react-datepicker";
+```
 
 ## License
 
@@ -161,4 +186,4 @@ MIT
 
 ---
 
-*Kenos UI*
+_Kenos UI_ — https://github.com/allysontsoares/kenos-ui/tree/main/packages/datepicker

package/dist/index.cjs

@@ -4,6 +4,7 @@ var React = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 var react = require('timescape/react');
 var reactDom = require('react-dom');
+var utils = require('@kenos-ui/utils');
 var reactDom$1 = require('@floating-ui/react-dom');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -418,6 +419,7 @@ function resolveConfig(props) {
     mode: props.mode ?? "single",
     locale: props.locale ?? (typeof navigator !== "undefined" ? navigator.language : "en-US"),
     readOnly: props.readOnly ?? false,
+    modal: props.modal ?? false,
     closeOnSelect: props.closeOnSelect ?? (props.mode !== "range" && props.mode !== "multiple"),
     ...props.weekStartsOn !== void 0 && { weekStartsOn: props.weekStartsOn },
     ...props.minDate !== void 0 && { minDate: props.minDate },
@@ -443,7 +445,7 @@ function resolveInitialValue(props) {
 }
 function useDatePicker(props) {
   const uid = React.useId();
-  const { mode, locale, weekStartsOn, minDate, maxDate, disabled, readOnly, closeOnSelect } = props;
+  const { mode, locale, weekStartsOn, minDate, maxDate, disabled, readOnly, closeOnSelect, modal } = props;
   const config = React.useMemo(
     () => resolveConfig({
       mode,
@@ -453,9 +455,10 @@ function useDatePicker(props) {
       maxDate,
       disabled,
       readOnly,
-      closeOnSelect
+      closeOnSelect,
+      modal
     }),
-    [mode, locale, weekStartsOn, minDate, maxDate, disabled, readOnly, closeOnSelect]
+    [mode, locale, weekStartsOn, minDate, maxDate, disabled, readOnly, closeOnSelect, modal]
   );
   const initialValue = resolveInitialValue(props);
   const [state, dispatch] = React.useReducer(
@@ -657,6 +660,7 @@ function Segments({
     }
     if (e.key === "Escape") {
       e.preventDefault();
+      e.stopPropagation();
       if (state.open) dispatch({ type: "CLOSE" });
     }
   }
@@ -807,76 +811,6 @@ function Trigger({ children, onClick, disabled, ...props }) {
     }
   );
 }
-function useClickOutside(refs, handler, enabled = true) {
-  const refsRef = React.useRef(refs);
-  refsRef.current = refs;
-  React.useEffect(() => {
-    if (!enabled) return;
-    function onPointerDown(e) {
-      const target = e.target;
-      if (refsRef.current.every((r) => !r.current?.contains(target))) {
-        handler();
-      }
-    }
-    document.addEventListener("pointerdown", onPointerDown, true);
-    return () => document.removeEventListener("pointerdown", onPointerDown, true);
-  }, [enabled, handler]);
-}
-
-// src/utils/aria.ts
-function getFocusableElements(container) {
-  const selector = [
-    "a[href]",
-    "button:not([disabled])",
-    "input:not([disabled])",
-    "select:not([disabled])",
-    "textarea:not([disabled])",
-    '[tabindex]:not([tabindex="-1"])'
-  ].join(", ");
-  return Array.from(container.querySelectorAll(selector)).filter(
-    (el) => !el.closest("[hidden]") && el.offsetParent !== null
-  );
-}
-
-// src/date-picker/use-focus-trap.ts
-function useFocusTrap(containerRef, enabled = true) {
-  React.useEffect(() => {
-    if (!enabled || !containerRef.current) return;
-    const container = containerRef.current;
-    function onKeyDown(e) {
-      if (e.key !== "Tab") return;
-      const focusable = getFocusableElements(container);
-      if (!focusable.length) return;
-      const first = focusable[0];
-      const last = focusable[focusable.length - 1];
-      if (e.shiftKey) {
-        if (document.activeElement === first) {
-          e.preventDefault();
-          last.focus();
-        }
-      } else {
-        if (document.activeElement === last) {
-          e.preventDefault();
-          first.focus();
-        }
-      }
-    }
-    const observer = new MutationObserver(() => {
-      const active = document.activeElement;
-      if (active?.getAttribute("role") === "spinbutton") return;
-      if (!container.contains(active)) {
-        const firstFocusable = getFocusableElements(container)[0];
-        firstFocusable?.focus();
-      }
-    });
-    observer.observe(container, { childList: true, subtree: true });
-    container.addEventListener("keydown", onKeyDown);
-    return () => {
-      container.removeEventListener("keydown", onKeyDown);
-      observer.disconnect();
-    };
-  }, [enabled, containerRef]);
-}
 function toPlacement(side, align) {
   return align === "center" ? side : `${side}-${align}`;
 }
@@ -975,12 +909,22 @@ function Content({
     },
     [setFloating]
   );
-  useClickOutside(
-    [contentRef, triggerRef, inputRef, input0Ref, input1Ref],
-    () => dispatch({ type: "CLOSE" }),
-    isOpen
-  );
-  useFocusTrap(contentRef, isOpen);
+  const close = React.useCallback(() => {
+    const source = state.openSource;
+    dispatch({ type: "CLOSE" });
+    utils.restoreFocus({
+      openSource: source === "input" ? "input" : source === "trigger" ? "trigger" : "unknown",
+      trigger: document.getElementById(ids.trigger),
+      input: document.getElementById(ids.input) ?? document.getElementById(`${ids.input}-0`)
+    });
+  }, [dispatch, ids.input, ids.trigger, state.openSource]);
+  utils.useClickOutside([contentRef, triggerRef, inputRef, input0Ref, input1Ref], close, isOpen);
+  utils.useEscapeKey({
+    enabled: isOpen,
+    stopPropagation: true,
+    onEscape: close
+  });
+  utils.useFocusTrap(contentRef, isOpen && config.modal);
   const [transitionsReady, setTransitionsReady] = React.useState(false);
   React.useEffect(() => {
     if (!isOpen || !isPositioned) {
@@ -1009,7 +953,7 @@ function Content({
       ref: mergedRef,
       id: ids.content,
       role: "dialog",
-      "aria-modal": "true",
+      "aria-modal": config.modal ? "true" : void 0,
       "aria-labelledby": ids.label,
       "data-state": isOpen ? "open" : "closed",
       style: {
@@ -1023,14 +967,7 @@ function Content({
         ...isOpen && !transitionsReady ? { transition: "none" } : void 0,
         ...style
       },
-      onKeyDown: (e) => {
-        if (e.key === "Escape") {
-          e.preventDefault();
-          dispatch({ type: "CLOSE" });
-          document.getElementById(ids.trigger)?.focus();
-        }
-        onKeyDown?.(e);
-      },
+      onKeyDown,
       ...props,
       children: [
         /* @__PURE__ */ jsxRuntime.jsx(