@nepdatejs/react 0.0.0-stage → 0.1.1

package/src/date-range-picker.tsx

@@ -0,0 +1,225 @@
+import { useRef, type CSSProperties, type ReactElement } from 'react';
+import {
+  getLocale,
+  type CalendarDate,
+  type CalendarSystem,
+  type LocaleCode,
+  type Weekday,
+} from '@nepdatejs/core';
+import type { HolidayInput, HolidayLookup } from '@nepdatejs/calendar';
+import type { RangeDetail, RangePreset, RangeValue } from '@nepdatejs/datepicker';
+import { restoreFocus } from '@nepdatejs/dom';
+import { CalendarBody } from './calendar-body';
+import { useDateRangePicker } from './hooks';
+import { Icon } from './icons';
+import { usePageLocale } from './page-locale';
+import { usePanel } from './panel';
+import type { PanelLayout } from '@nepdatejs/dom';
+import { PANEL_WIDTH, PANEL_WIDTH_WITH_PRESETS, PanelBody } from './presets';
+
+export interface DateRangePickerProps {
+  value?: RangeValue | undefined;
+  defaultValue?: RangeValue | undefined;
+  onChange?: ((value: RangeValue, detail: RangeDetail) => void) | undefined;
+  calendar?: CalendarSystem | undefined;
+  defaultCalendar?: CalendarSystem | undefined;
+  min?: string | undefined;
+  max?: string | undefined;
+  minDays?: number | undefined;
+  maxDays?: number | undefined;
+  /** Shortcuts beside the calendar: 'last7Days', 'thisMonth', 'thisFiscalYear', … or { id, label, resolve }. */
+  presets?: readonly RangePreset[] | undefined;
+  isDateDisabled?: ((date: CalendarDate) => boolean) | undefined;
+  holidays?: readonly HolidayInput[] | HolidayLookup | undefined;
+  locale?: LocaleCode | undefined;
+  weekStartsOn?: Weekday | undefined;
+  weekendDays?: readonly Weekday[] | undefined;
+  showOtherCalendar?: boolean | undefined;
+  today?: CalendarDate | undefined;
+  /** Field names for plain form posts. */
+  startName?: string | undefined;
+  endName?: string | undefined;
+  startLabel?: string | undefined;
+  endLabel?: string | undefined;
+  /** Show a "Fiscal year" button that switches the panel to fiscal-year tiles. */
+  fiscalYearView?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Add the dashes of YYYY-MM-DD while the user types digits. Default true. */
+  mask?: boolean | undefined;
+  /** Show the calendar in the page, always open, instead of in a popover. */
+  inline?: boolean | undefined;
+  /** 'sheet' opens a bottom sheet; 'popover' sits beside the field; 'auto' (default) uses the sheet below 480px. */
+  panelLayout?: PanelLayout | undefined;
+  theme?: 'light' | 'dark' | 'auto' | undefined;
+  className?: string | undefined;
+}
+
+/** Two BS/AD date fields sharing one calendar panel in range mode. */
+export function DateRangePicker({
+  startName,
+  endName,
+  startLabel,
+  endLabel,
+  fiscalYearView = false,
+  disabled = false,
+  panelLayout,
+  theme,
+  className,
+  ...options
+}: DateRangePickerProps): ReactElement {
+  const locale = usePageLocale(options.locale);
+  const picker = useDateRangePicker({ ...options, locale });
+  const { state, store, calendar } = picker;
+  const labels = getLocale(locale);
+  const field = useRef<HTMLDivElement | null>(null);
+  const row = useRef<HTMLDivElement | null>(null);
+  const panel = useRef<HTMLDivElement | null>(null);
+  const start = useRef<HTMLInputElement | null>(null);
+
+  const panelWidth = state.presets.length > 0 ? PANEL_WIDTH_WITH_PRESETS : PANEL_WIDTH;
+  usePanel(
+    state.open && !state.inline,
+    { anchor: row, panel, field, returnFocus: start },
+    () => {
+      store.actions.close();
+    },
+    calendar.focusGrid,
+    panelWidth,
+    panelLayout,
+  );
+
+  const invalid = (which: 'start' | 'end'): boolean =>
+    state.error !== null &&
+    (state.error.field === which || state.error.field === 'range');
+
+  return (
+    <div
+      ref={field}
+      className={className ? `ndp-field ${className}` : 'ndp-field'}
+      data-ndp-theme={theme}
+    >
+      <div ref={row} className="ndp-range">
+        <div
+          className="ndp-input"
+          data-invalid={invalid('start') || undefined}
+          data-disabled={disabled || undefined}
+        >
+          <input
+            ref={start}
+            className="ndp-input__control"
+            {...picker.getInputProps('start')}
+            aria-label={startLabel}
+            disabled={disabled}
+          />
+        </div>
+        <span className="ndp-range__separator" aria-hidden="true">
+          →
+        </span>
+        <div
+          className="ndp-input"
+          data-invalid={invalid('end') || undefined}
+          data-disabled={disabled || undefined}
+        >
+          <input
+            className="ndp-input__control"
+            {...picker.getInputProps('end')}
+            aria-label={endLabel}
+            disabled={disabled}
+          />
+          {!state.inline && (
+            <span className="ndp-input__actions">
+              <button
+                className="ndp-icon-button"
+                disabled={disabled}
+                {...picker.getToggleProps()}
+              >
+                <Icon name="calendar" />
+              </button>
+            </span>
+          )}
+        </div>
+      </div>
+      {state.error && (
+        <p id={picker.ids.hint} className="ndp-hint" data-error aria-live="polite">
+          {state.error.message}
+        </p>
+      )}
+      {startName !== undefined && (
+        <input
+          type="hidden"
+          name={startName}
+          value={state.value.start}
+          disabled={disabled}
+        />
+      )}
+      {endName !== undefined && (
+        <input type="hidden" name={endName} value={state.value.end} disabled={disabled} />
+      )}
+      {state.open && (
+        <div
+          ref={panel}
+          className="ndp-panel"
+          popover={state.inline ? undefined : 'manual'}
+          data-layout={state.inline ? 'inline' : undefined}
+          style={
+            state.inline
+              ? ({ '--ndp-panel-width': `${String(panelWidth)}px` } as CSSProperties)
+              : undefined
+          }
+          data-ndp-theme={theme}
+          {...picker.getPanelProps()}
+        >
+          <PanelBody
+            presets={state.presets}
+            label={labels.labels.presets}
+            onPreset={(id) => {
+              if (store.actions.applyPreset(id) && !store.getState().open) {
+                restoreFocus(start.current);
+              }
+            }}
+          >
+            <CalendarBody bindings={calendar} />
+          </PanelBody>
+          {(state.canSwitchCalendar || fiscalYearView) && (
+            <div className="ndp-panel__footer">
+              {state.canSwitchCalendar ? (
+                <div
+                  className="ndp-segment"
+                  role="group"
+                  aria-label={labels.labels.calendar}
+                >
+                  {(['BS', 'AD'] as const).map((option) => (
+                    <button
+                      key={option}
+                      className="ndp-segment__item"
+                      {...picker.getCalendarOptionProps(option)}
+                    >
+                      {labels.calendarNames[option]}
+                    </button>
+                  ))}
+                </div>
+              ) : (
+                <span />
+              )}
+              {fiscalYearView && (
+                <button
+                  type="button"
+                  className="ndp-button"
+                  aria-pressed={state.calendarState.view === 'fiscal'}
+                  onClick={() => {
+                    store.calendar.actions.setView(
+                      state.calendarState.view === 'fiscal' ? 'day' : 'fiscal',
+                    );
+                    calendar.focusGrid();
+                  }}
+                >
+                  {labels.labels.fiscalYear}
+                </button>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/date-text.tsx

@@ -0,0 +1,110 @@
+import type { ReactElement } from 'react';
+import {
+  formatDate,
+  fromIsoDate,
+  fromIsoTimestamp,
+  toCalendar,
+  type CalendarSystem,
+  type DateFormatPattern,
+  type LocaleCode,
+} from '@nepdatejs/core';
+
+export interface DateTextProps {
+  /** An AD date or timestamp from the server ("2026-09-26" or an ISO timestamp). */
+  value: string | null | undefined;
+  /** Which calendar to show first. Default 'BS'. */
+  calendar?: CalendarSystem | undefined;
+  /** Also show the day in the other calendar, muted. Default true. */
+  withEquivalent?: boolean | undefined;
+  format?: DateFormatPattern | undefined;
+  locale?: LocaleCode | undefined;
+  fallback?: string | undefined;
+  className?: string | undefined;
+}
+
+/**
+ * A server date shown in BS (or AD), with the other calendar alongside:
+ * "10 Ashwin 2083 · 26 Sep 2026". No hooks, so it works in server components.
+ */
+export function DateText({
+  value,
+  calendar = 'BS',
+  withEquivalent = true,
+  format = 'long',
+  locale,
+  fallback = '—',
+  className,
+}: DateTextProps): ReactElement {
+  const date = fromIsoDate(value);
+  if (!date) {
+    return <span className={className}>{fallback}</span>;
+  }
+  const other: CalendarSystem = calendar === 'BS' ? 'AD' : 'BS';
+
+  return (
+    <time dateTime={formatDate(date, 'Y-m-d')} className={className}>
+      {formatDate(toCalendar(date, calendar), format, locale)}
+      {withEquivalent && (
+        <span className="ndp-muted" style={{ color: 'var(--ndp-text-muted, #64748b)' }}>
+          {' · '}
+          {formatDate(toCalendar(date, other), other === 'AD' ? 'j M Y' : format, locale)}
+        </span>
+      )}
+    </time>
+  );
+}
+
+/**
+ * A server date as short text: "12 Ashwin 2083", keeping the time of day when
+ * the value has one. A timestamp with a zone is read in the configured zone
+ * (Nepal by default). Anything that is not a date is returned unchanged.
+ */
+export function shortDate(value: string | null | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  const instant = fromIsoTimestamp(value);
+  const date = instant?.date ?? fromIsoDate(value);
+  if (!date) {
+    return value;
+  }
+  const time = instant?.time ?? /[T ](\d{2}:\d{2})/.exec(value)?.[1];
+
+  return `${formatDate(toCalendar(date, 'BS'), 'j F Y')}${time ? `, ${time}` : ''}`;
+}
+
+/** A server date as documents print it, in both calendars: "31 Shrawan 2083 (16 Aug 2026)". */
+export function bothDates(value: string | null | undefined): string {
+  const date = fromIsoDate(value);
+
+  return date
+    ? `${formatDate(toCalendar(date, 'BS'), 'j F Y')} (${formatDate(date, 'j M Y')})`
+    : (value ?? '');
+}
+
+/** A server date for a table cell or list row, with the AD day on hover. */
+export function ShortDate({
+  value,
+  fallback = '—',
+  className,
+}: {
+  value: string | null | undefined;
+  fallback?: string | undefined;
+  className?: string | undefined;
+}): ReactElement {
+  const text = shortDate(value);
+  const date = fromIsoDate(value);
+  if (!text) {
+    return <span className={className}>{fallback}</span>;
+  }
+
+  return (
+    <time
+      dateTime={value ?? undefined}
+      title={date ? formatDate(date, 'j M Y') : undefined}
+      className={className}
+    >
+      {text}
+    </time>
+  );
+}

package/src/date-time-picker.tsx

@@ -0,0 +1,289 @@
+import { useRef, type CSSProperties, type ReactElement } from 'react';
+import {
+  getLocale,
+  type CalendarDate,
+  type CalendarSystem,
+  type LocaleCode,
+  type Weekday,
+} from '@nepdatejs/core';
+import type { HolidayInput, HolidayLookup } from '@nepdatejs/calendar';
+import type { DateTimeDetail, SinglePreset } from '@nepdatejs/datepicker';
+import { CalendarBody } from './calendar-body';
+import { popupProps, useDateTimePicker } from './hooks';
+import { Icon } from './icons';
+import { usePageLocale } from './page-locale';
+import { usePanel } from './panel';
+import type { PanelLayout } from '@nepdatejs/dom';
+import {
+  PANEL_WIDTH,
+  PANEL_WIDTH_WITH_PRESETS,
+  PanelBody,
+  TIME_COLUMNS_WIDTH,
+} from './presets';
+import { TimeColumns } from './time-columns';
+
+export interface DateTimePickerProps {
+  /** ISO timestamp with offset ("2026-10-18T14:30:00+05:45") or "". */
+  value?: string | undefined;
+  defaultValue?: string | undefined;
+  onChange?: ((value: string, detail: DateTimeDetail | null) => void) | undefined;
+  /** The zone the picker shows and the value's offset. Default Asia/Kathmandu (core config). */
+  timeZone?: string | undefined;
+  hour12?: boolean | undefined;
+  /** Minutes in the column (1–30). Default 5. */
+  minuteStep?: number | undefined;
+  /** Time used when a day is picked first. Default "00:00". */
+  defaultTime?: string | undefined;
+  calendar?: CalendarSystem | undefined;
+  defaultCalendar?: CalendarSystem | undefined;
+  /** Earliest and latest days, AD "YYYY-MM-DD". */
+  min?: string | undefined;
+  max?: string | undefined;
+  isDateDisabled?: ((date: CalendarDate) => boolean) | undefined;
+  holidays?: readonly HolidayInput[] | HolidayLookup | undefined;
+  presets?: readonly SinglePreset[] | undefined;
+  locale?: LocaleCode | undefined;
+  weekStartsOn?: Weekday | undefined;
+  today?: CalendarDate | undefined;
+  /** Submit the ISO value with a plain form. */
+  name?: string | undefined;
+  id?: string | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Add the dashes of YYYY-MM-DD while the user types digits. Default true. */
+  mask?: boolean | undefined;
+  /** Show the calendar in the page, always open, instead of in a popover. */
+  inline?: boolean | undefined;
+  /** 'sheet' opens a bottom sheet; 'popover' sits beside the field; 'auto' (default) uses the sheet below 480px. */
+  panelLayout?: PanelLayout | undefined;
+  theme?: 'light' | 'dark' | 'auto' | undefined;
+  className?: string | undefined;
+  /** Accessible names for the two inputs. */
+  'aria-label'?: string | undefined;
+  timeLabel?: string | undefined;
+}
+
+/** A BS/AD date and time field. The value is one instant, with the zone's offset. */
+export function DateTimePicker({
+  name,
+  required,
+  disabled = false,
+  panelLayout,
+  theme,
+  className,
+  'aria-label': ariaLabel,
+  timeLabel,
+  ...options
+}: DateTimePickerProps): ReactElement {
+  const locale = usePageLocale(options.locale);
+  const picker = useDateTimePicker({ ...options, locale });
+  const { state, store, calendar, ids } = picker;
+  const labels = getLocale(locale);
+  const field = useRef<HTMLDivElement | null>(null);
+  const row = useRef<HTMLDivElement | null>(null);
+  const panel = useRef<HTMLDivElement | null>(null);
+  const dateInput = useRef<HTMLInputElement | null>(null);
+
+  const panelWidth =
+    (state.presets.length > 0 ? PANEL_WIDTH_WITH_PRESETS : PANEL_WIDTH) +
+    TIME_COLUMNS_WIDTH;
+  usePanel(
+    state.open && !state.inline,
+    { anchor: row, panel, field, returnFocus: dateInput },
+    () => {
+      store.actions.close();
+    },
+    calendar.focusGrid,
+    panelWidth,
+    panelLayout,
+  );
+
+  const hint = state.error?.message ?? state.equivalentText;
+  const invalid = (which: 'date' | 'time'): boolean => state.error?.field === which;
+
+  return (
+    <div
+      ref={field}
+      className={className ? `ndp-field ${className}` : 'ndp-field'}
+      data-ndp-theme={theme}
+    >
+      <div ref={row} className="ndp-datetime">
+        <div
+          className="ndp-input"
+          data-invalid={invalid('date') || undefined}
+          data-disabled={disabled || undefined}
+        >
+          <input
+            ref={dateInput}
+            id={ids.date}
+            className="ndp-input__control"
+            {...popupProps(state)}
+            type="text"
+            inputMode="numeric"
+            autoComplete="off"
+            value={state.dateText}
+            placeholder={state.placeholder}
+            aria-label={ariaLabel}
+            aria-controls={ids.panel}
+            aria-invalid={invalid('date') || undefined}
+            aria-describedby={hint ? ids.hint : undefined}
+            required={required}
+            disabled={disabled}
+            onChange={(event) => {
+              store.actions.typeDate(event.target.value);
+            }}
+            onBlur={() => {
+              store.actions.blurDate();
+            }}
+            onKeyDown={(event) => {
+              if (event.key === 'ArrowDown' && (event.altKey || state.dateText === '')) {
+                event.preventDefault();
+                store.actions.open();
+              }
+            }}
+          />
+          {!state.inline && (
+            <span className="ndp-input__actions">
+              <button
+                type="button"
+                className="ndp-icon-button"
+                disabled={disabled}
+                aria-label={labels.labels.openCalendar}
+                aria-expanded={state.open}
+                aria-controls={ids.panel}
+                onClick={() => {
+                  store.actions.toggle();
+                }}
+              >
+                <Icon name="calendar" />
+              </button>
+            </span>
+          )}
+        </div>
+        <div
+          className="ndp-input ndp-input--time"
+          data-invalid={invalid('time') || undefined}
+          data-disabled={disabled || undefined}
+        >
+          <input
+            id={ids.time}
+            className="ndp-input__control"
+            type="text"
+            inputMode="text"
+            autoComplete="off"
+            value={state.timeText}
+            placeholder={state.timePlaceholder}
+            aria-label={timeLabel ?? labels.labels.time}
+            aria-invalid={invalid('time') || undefined}
+            aria-describedby={hint ? ids.hint : undefined}
+            disabled={disabled}
+            onChange={(event) => {
+              store.actions.typeTime(event.target.value);
+            }}
+            onBlur={() => {
+              store.actions.blurTime();
+            }}
+          />
+        </div>
+      </div>
+      {hint !== null && (
+        <p
+          id={ids.hint}
+          className="ndp-hint"
+          data-error={state.error ? true : undefined}
+          aria-live="polite"
+        >
+          {hint}
+        </p>
+      )}
+      {name !== undefined && (
+        <input type="hidden" name={name} value={state.value} disabled={disabled} />
+      )}
+      {state.open && (
+        <div
+          ref={panel}
+          id={ids.panel}
+          className="ndp-panel"
+          popover={state.inline ? undefined : 'manual'}
+          data-layout={state.inline ? 'inline' : undefined}
+          style={
+            state.inline
+              ? ({ '--ndp-panel-width': `${String(panelWidth)}px` } as CSSProperties)
+              : undefined
+          }
+          role={state.inline ? 'group' : 'dialog'}
+          aria-label={labels.labels.chooseDate}
+          data-ndp-theme={theme}
+        >
+          <PanelBody
+            presets={state.presets}
+            label={labels.labels.presets}
+            onPreset={(presetId) => {
+              store.actions.applyPreset(presetId);
+            }}
+          >
+            <CalendarBody bindings={calendar} />
+            <TimeColumns
+              hours={state.hours}
+              minutes={state.minutes}
+              locale={options.locale}
+              onHour={(hour) => {
+                store.actions.selectHour(hour);
+              }}
+              onMinute={(minute) => {
+                store.actions.selectMinute(minute);
+              }}
+            />
+          </PanelBody>
+          <div className="ndp-panel__footer">
+            {state.canSwitchCalendar ? (
+              <div
+                className="ndp-segment"
+                role="group"
+                aria-label={labels.labels.calendar}
+              >
+                {(['BS', 'AD'] as const).map((option) => (
+                  <button
+                    key={option}
+                    type="button"
+                    className="ndp-segment__item"
+                    aria-pressed={state.calendar === option}
+                    onClick={() => {
+                      store.actions.switchCalendar(option);
+                    }}
+                  >
+                    {labels.calendarNames[option]}
+                  </button>
+                ))}
+              </div>
+            ) : (
+              <span />
+            )}
+            <span>
+              <button
+                type="button"
+                className="ndp-button"
+                onClick={() => {
+                  store.actions.selectNow();
+                }}
+              >
+                {labels.labels.now}
+              </button>
+              <button
+                type="button"
+                className="ndp-button"
+                data-variant="primary"
+                onClick={() => {
+                  store.actions.close();
+                  dateInput.current?.focus();
+                }}
+              >
+                {labels.labels.done}
+              </button>
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/headless.ts

@@ -0,0 +1,21 @@
+/** @nepdatejs/react/headless: hooks only; no markup, no CSS. */
+export {
+  useCalendar,
+  useDatePicker,
+  useDateRangePicker,
+  useDateTimePicker,
+  useMultiDatePicker,
+  type DatePickerBindings,
+  type DateTimePickerBindings,
+  type DateRangePickerBindings,
+  type MultiDatePickerBindings,
+  type InputProps,
+  type PanelProps,
+} from './hooks';
+export {
+  useCalendarBindings,
+  type ButtonProps,
+  type CalendarBindings,
+  type GridProps,
+} from './bindings';
+export { deepEqual, useStore } from './use-store';