@dashforge/tw 1.1.0 → 1.1.1

package/src/components/TimePicker/TimePicker.tsx

@@ -1,274 +0,0 @@
-import { useCallback, useContext, useEffect, useId, useRef, useState } from 'react';
-import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
-import type { DashFormBridge, FieldRegistration } from '@dashforge/ui-core';
-import { useDashFieldMeta } from '@dashforge/forms';
-import {
-  formatTime,
-  generateTimeOptions,
-  timeStringToMinutes,
-} from '@dashforge/calendar-core';
-import { cn } from '../../utils/cn.js';
-import { useAccessState } from '../../hooks/useAccessState.js';
-import { resolveValidationState } from '../_shared/resolveValidationState.js';
-import { Popover } from '../Popover/Popover.js';
-import { timePickerVariants } from './timePicker.variants.js';
-import type { TimePickerProps } from './timePicker.types.js';
-
-// Inline 16×16 stroke clock glyph — no icon dependency (tw convention).
-function ClockIcon() {
-  return (
-    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-      <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" />
-      <path
-        d="M8 4.5V8l2.4 1.4"
-        stroke="currentColor"
-        strokeWidth="1.5"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      />
-    </svg>
-  );
-}
-
-/**
- * Dashforge TW `<TimePicker>` — a form-bound time-of-day field.
- *
- * A read-only trigger button paired with a time-list popover (Radix
- * Popover). Integrates with the Dashforge form bridge + RBAC.
- *
- * Storage contract: a canonical 24-hour `"HH:mm"` string, or `null` —
- * shared with the MUI `@dashforge/ui` `TimePicker`. `hour12` is display-only.
- */
-export function TimePicker(props: TimePickerProps) {
-  const {
-    name,
-    rules,
-    label,
-    helperText,
-    error,
-    required,
-    disabled,
-    placeholder,
-    layout = 'stacked',
-    visibleWhen,
-    access,
-    value: explicitValue,
-    defaultValue,
-    onChange,
-    minTime,
-    maxTime,
-    stepMinutes,
-    hour12 = false,
-    fullWidth,
-    sx,
-    slotProps,
-    testId,
-  } = props;
-
-  const bridge = useContext(DashFormContext) as DashFormBridge | null;
-  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-  const fieldMeta = useDashFieldMeta(name);
-  const accessState = useAccessState(access);
-
-  const fieldId = useId();
-  const helperId = `${fieldId}-help`;
-
-  const [isOpen, setIsOpen] = useState(false);
-  const [internalValue, setInternalValue] = useState<string | null>(
-    defaultValue ?? null,
-  );
-
-  const unregisterRef = useRef({ bridge, name });
-  unregisterRef.current = { bridge, name };
-  const isMountedRef = useRef(false);
-  useEffect(() => {
-    isMountedRef.current = true;
-    return () => {
-      isMountedRef.current = false;
-      const { bridge: cap, name: capName } = unregisterRef.current;
-      queueMicrotask(() => {
-        if (!isMountedRef.current) cap?.unregister?.(capName);
-      });
-    };
-  }, []);
-
-  const effectiveDisabled = Boolean(disabled) || accessState.disabled;
-  const isInteractive = !effectiveDisabled && !accessState.readonly;
-  const isFormMode = Boolean(bridge?.register);
-
-  let resolvedError = error;
-  let resolvedHelperText: typeof helperText = helperText;
-  let registration: FieldRegistration | null = null;
-  let resolvedValue: string | null;
-
-  if (isFormMode && bridge) {
-    registration = bridge.register(name, rules);
-    const validation = resolveValidationState(name, bridge, error, helperText);
-    resolvedError = validation.error;
-    resolvedHelperText = validation.helperText;
-    if (explicitValue !== undefined) {
-      resolvedValue = explicitValue;
-    } else {
-      const bv = fieldMeta.value;
-      resolvedValue = bv == null ? null : String(bv);
-    }
-  } else if (explicitValue !== undefined) {
-    resolvedValue = explicitValue;
-  } else {
-    resolvedValue = internalValue;
-  }
-
-  const registrationRefFn = registration?.ref;
-  const triggerRef = useCallback(
-    (instance: HTMLButtonElement | null) => {
-      if (typeof registrationRefFn === 'function') {
-        registrationRefFn(instance);
-      }
-    },
-    [registrationRefFn],
-  );
-
-  if (!isVisible) return null;
-  if (!accessState.visible) return null;
-
-  const v = timePickerVariants({ layout, error: resolvedError, fullWidth });
-  const displayValue =
-    resolvedValue != null && resolvedValue !== ''
-      ? formatTime(resolvedValue, { hour12 })
-      : '';
-
-  const options = generateTimeOptions({
-    ...(minTime !== undefined && { start: minTime }),
-    ...(maxTime !== undefined && { end: maxTime }),
-    ...(stepMinutes !== undefined && { stepMinutes }),
-  });
-  const minMinutes = timeStringToMinutes(minTime ?? '00:00') ?? 0;
-  const maxMinutes = timeStringToMinutes(maxTime ?? '23:59') ?? 1439;
-  const isTimeDisabled = (time: string): boolean => {
-    const minutes = timeStringToMinutes(time);
-    return minutes === null || minutes < minMinutes || minutes > maxMinutes;
-  };
-
-  const commitValue = (next: string | null) => {
-    if (isFormMode && bridge) {
-      bridge.setValue?.(name, next);
-      void registration?.onChange?.({
-        target: { name, value: next ?? '' },
-        type: 'change',
-      });
-    } else if (explicitValue === undefined) {
-      setInternalValue(next);
-    }
-    onChange?.(next);
-  };
-
-  const markTouched = () => {
-    if (isFormMode && bridge) {
-      const committed = bridge.getValue(name);
-      void registration?.onBlur?.({
-        target: { name, value: committed == null ? '' : String(committed) },
-        type: 'blur',
-      });
-    }
-  };
-
-  const handleOpenChange = (next: boolean) => {
-    if (next && !isInteractive) {
-      return;
-    }
-    setIsOpen(next);
-    if (!next) {
-      markTouched();
-    }
-  };
-
-  const handleSelect = (time: string) => {
-    if (isTimeDisabled(time)) {
-      return;
-    }
-    commitValue(time);
-    setIsOpen(false);
-    markTouched();
-  };
-
-  return (
-    <div
-      data-testid={testId}
-      className={cn(v.root(), sx, slotProps?.root?.className)}
-    >
-      {label && (
-        <label
-          htmlFor={fieldId}
-          className={cn(v.label(), slotProps?.label?.className)}
-        >
-          {label}
-          {required && (
-            <span
-              aria-hidden="true"
-              className={cn(v.requiredMark(), slotProps?.requiredMark?.className)}
-            >
-              *
-            </span>
-          )}
-        </label>
-      )}
-
-      <Popover
-        open={isOpen}
-        onOpenChange={handleOpenChange}
-        side="bottom"
-        align="start"
-        content={
-          <div role="listbox" aria-label="Time options" className={v.list()}>
-            {options.map((time) => (
-              <button
-                key={time}
-                type="button"
-                role="option"
-                aria-selected={time === resolvedValue}
-                aria-disabled={isTimeDisabled(time)}
-                className={v.option()}
-                onClick={() => {
-                  handleSelect(time);
-                }}
-              >
-                {formatTime(time, { hour12 })}
-              </button>
-            ))}
-          </div>
-        }
-      >
-        <button
-          type="button"
-          id={fieldId}
-          ref={triggerRef}
-          disabled={effectiveDisabled}
-          aria-invalid={resolvedError ? true : undefined}
-          aria-describedby={resolvedHelperText ? helperId : undefined}
-          className={cn(v.trigger(), slotProps?.trigger?.className)}
-        >
-          <span className={displayValue ? v.value() : v.placeholder()}>
-            {displayValue || placeholder || 'Select a time'}
-          </span>
-          <span className={v.icon()}>
-            <ClockIcon />
-          </span>
-        </button>
-      </Popover>
-
-      {resolvedHelperText && (
-        <p
-          id={helperId}
-          className={cn(
-            resolvedError ? v.errorText() : v.helperText(),
-            resolvedError
-              ? slotProps?.errorText?.className
-              : slotProps?.helperText?.className,
-          )}
-        >
-          {resolvedHelperText}
-        </p>
-      )}
-    </div>
-  );
-}

package/src/components/TimePicker/timePicker.types.ts

@@ -1,69 +0,0 @@
-import type { ReactNode } from 'react';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-
-/** Per-slot `className` overrides for `<TimePicker>`. */
-export interface TimePickerSlotProps {
-  root?: { className?: string };
-  label?: { className?: string };
-  requiredMark?: { className?: string };
-  trigger?: { className?: string };
-  helperText?: { className?: string };
-  errorText?: { className?: string };
-}
-
-/**
- * Props for the `<TimePicker>` form field (Tailwind skin).
- *
- * A read-only trigger paired with a `<Calendar>`-style time-list popover.
- * The stored value is a canonical 24-hour `"HH:mm"` string, or `null`.
- * 12-hour notation (`hour12`) is display-only. No date, no timezone.
- *
- * The prop surface mirrors the MUI `@dashforge/ui` `TimePicker`.
- */
-export interface TimePickerProps {
-  /** Field name — the bridge registration key. Required. */
-  name: string;
-  /** Validation rules forwarded to the form bridge. */
-  rules?: unknown;
-  /** Field label. */
-  label?: ReactNode;
-  /** Helper text below the control (overrides a bridge error message). */
-  helperText?: ReactNode;
-  /** Explicit error state (overrides the bridge's auto error). */
-  error?: boolean;
-  /** Marks the field required (adds the label asterisk). */
-  required?: boolean;
-  /** Disables the field. */
-  disabled?: boolean;
-  /** Placeholder shown when no time is selected. */
-  placeholder?: string;
-  /** Label/control layout. */
-  layout?: 'stacked' | 'inline';
-  /** Reactive visibility predicate evaluated against the form engine. */
-  visibleWhen?: (engine: Engine) => boolean;
-  /** RBAC access requirement. */
-  access?: AccessRequirement;
-  /** Controlled value — `"HH:mm"` (24-hour) or `null`. */
-  value?: string | null;
-  /** Uncontrolled initial value. */
-  defaultValue?: string | null;
-  /** Fired with the new time (or `null` when cleared). */
-  onChange?: (value: string | null) => void;
-  /** Earliest selectable time, `"HH:mm"`. Default `"00:00"`. */
-  minTime?: string;
-  /** Latest selectable time, `"HH:mm"`. Default `"23:30"`. */
-  maxTime?: string;
-  /** Step between time-list options, in minutes. Default `30`. */
-  stepMinutes?: number;
-  /** Render the time list in 12-hour notation. Default `false`. */
-  hour12?: boolean;
-  /** Stretches the field to its container width. */
-  fullWidth?: boolean;
-  /** Root-level Tailwind class override. */
-  sx?: string;
-  /** Per-slot `className` overrides. */
-  slotProps?: TimePickerSlotProps;
-  /** Test id applied to the field root. */
-  testId?: string;
-}

package/src/components/TimePicker/timePicker.variants.ts

@@ -1,53 +0,0 @@
-import { tv } from 'tailwind-variants';
-
-/**
- * Slots for `<TimePicker>` — a bridge-integrated time field whose trigger
- * is a `<button>` styled as an input, opening a time-list popover.
- *
- * Theme identity: bare neutral / brand token-backed classes only — no
- * `dark:` variants on the neutral palette (the preset CSS-var swap
- * auto-inverts). See `_shared/themeIdentity.test.ts`.
- */
-export const timePickerVariants = tv({
-  slots: {
-    root: 'flex flex-col',
-    label: 'block text-sm font-medium text-neutral-900 mb-1',
-    requiredMark: 'text-danger-500 ml-0.5',
-    trigger:
-      'flex items-center gap-2 h-10 min-w-[10rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
-    value: 'flex-1 truncate text-left',
-    placeholder: 'flex-1 truncate text-left text-neutral-400',
-    icon: 'shrink-0 text-[1rem] text-neutral-500',
-    list: 'flex max-h-64 min-w-[8rem] flex-col gap-0.5 overflow-y-auto p-1',
-    option:
-      'flex w-full cursor-pointer items-center rounded px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600 aria-disabled:cursor-default aria-disabled:text-neutral-300 aria-disabled:opacity-60 aria-disabled:hover:bg-transparent',
-    helperText: 'mt-1 text-sm text-neutral-600',
-    errorText: 'mt-1 text-sm text-danger-600',
-  },
-  variants: {
-    layout: {
-      stacked: {},
-      inline: {
-        root: 'flex-row items-start gap-3',
-        label: 'mb-0 pt-2.5 whitespace-nowrap shrink-0',
-      },
-    },
-    error: {
-      true: {
-        trigger:
-          'border-danger-500 hover:border-danger-500 focus-visible:border-danger-500 focus-visible:ring-danger-500/30',
-      },
-    },
-    fullWidth: {
-      true: {
-        root: 'w-full',
-        trigger: 'w-full min-w-0',
-      },
-    },
-  },
-  defaultVariants: {
-    layout: 'stacked',
-    error: false,
-    fullWidth: false,
-  },
-});

package/src/components/Tooltip/Tooltip.test.tsx

@@ -1,73 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, afterEach, beforeAll } from 'vitest';
-import { render, screen, cleanup } from '@testing-library/react';
-import { Tooltip } from './Tooltip.js';
-
-void React;
-afterEach(() => cleanup());
-
-// jsdom doesn't implement ResizeObserver — Radix Floating UI requires it.
-// Shim with a noop before any test mounts a Tooltip.
-beforeAll(() => {
-  if (typeof globalThis.ResizeObserver === 'undefined') {
-    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
-      observe() {}
-      unobserve() {}
-      disconnect() {}
-    };
-  }
-  if (typeof globalThis.DOMRect === 'undefined') {
-    (globalThis as unknown as { DOMRect: unknown }).DOMRect = class {
-      static fromRect(r?: DOMRectInit) {
-        return new (globalThis as unknown as { DOMRect: new (x: number, y: number, w: number, h: number) => unknown }).DOMRect(
-          r?.x ?? 0, r?.y ?? 0, r?.width ?? 0, r?.height ?? 0
-        );
-      }
-      constructor(public x = 0, public y = 0, public width = 0, public height = 0) {}
-    };
-  }
-});
-
-describe('Tooltip — rendering', () => {
-  it('renders the trigger (children) always', () => {
-    render(
-      <Tooltip content="Tip text">
-        <button>Trigger</button>
-      </Tooltip>
-    );
-    expect(screen.queryByRole('button', { name: 'Trigger' })).not.toBeNull();
-  });
-
-  it('renders content when controlled open=true', () => {
-    render(
-      <Tooltip content="Tip text" open onOpenChange={() => {}}>
-        <button>Trigger</button>
-      </Tooltip>
-    );
-    expect(screen.queryAllByText('Tip text').length).toBeGreaterThan(0);
-  });
-
-  it('does not render content when controlled open=false', () => {
-    render(
-      <Tooltip content="Tip text" open={false} onOpenChange={() => {}}>
-        <button>Trigger</button>
-      </Tooltip>
-    );
-    expect(screen.queryByText('Tip text')).toBeNull();
-  });
-});
-
-describe('Tooltip — placement props', () => {
-  it.each(['top', 'right', 'bottom', 'left'] as const)(
-    'renders side=%s without crashing',
-    (side) => {
-      render(
-        <Tooltip content="Tip" open side={side} onOpenChange={() => {}}>
-          <button>Trigger</button>
-        </Tooltip>
-      );
-      expect(screen.queryByRole('button', { name: 'Trigger' })).not.toBeNull();
-    }
-  );
-});

package/src/components/Tooltip/Tooltip.tsx

@@ -1,70 +0,0 @@
-import * as RadixTooltip from '@radix-ui/react-tooltip';
-import { cn } from '../../utils/cn.js';
-import { tooltipVariants } from './tooltip.variants.js';
-import type { TooltipProps } from './tooltip.types.js';
-
-/**
- * Dashforge TW `<Tooltip>` — hoverable / focusable tooltip.
- *
- * Built on `@radix-ui/react-tooltip`:
- *  - APG tooltip pattern: `role="tooltip"`, `aria-describedby` wired
- *    to the trigger automatically (Radix manages the id linkage).
- *  - Shows on hover OR keyboard focus.
- *  - Dismissed on Escape or pointer leave.
- *
- * Wrap any single React node — it becomes the trigger via Radix's
- * `asChild` slot. The trigger inherits `aria-describedby` so screen
- * readers announce the tooltip content along with the trigger.
- *
- * @example
- * ```tsx
- * <Tooltip content="Delete this item">
- *   <Button variant="ghost">
- *     <TrashIcon />
- *   </Button>
- * </Tooltip>
- * ```
- *
- * Each consumer can also wrap the entire app once in
- * `<RadixTooltip.Provider>` to share delay/skip configuration; we
- * include a per-component provider here for ease-of-use.
- */
-export function Tooltip(props: TooltipProps) {
-  const {
-    children,
-    content,
-    side = 'top',
-    align = 'center',
-    hideArrow = false,
-    delayDuration = 200,
-    open,
-    onOpenChange,
-    sideOffset = 4,
-    slotProps,
-  } = props;
-
-  const v = tooltipVariants();
-
-  return (
-    <RadixTooltip.Provider delayDuration={delayDuration}>
-      <RadixTooltip.Root open={open} onOpenChange={onOpenChange}>
-        <RadixTooltip.Trigger asChild>{children}</RadixTooltip.Trigger>
-        <RadixTooltip.Portal>
-          <RadixTooltip.Content
-            side={side}
-            align={align}
-            sideOffset={sideOffset}
-            className={cn(v.content(), slotProps?.content?.className)}
-          >
-            {content}
-            {!hideArrow && (
-              <RadixTooltip.Arrow
-                className={cn(v.arrow(), slotProps?.arrow?.className)}
-              />
-            )}
-          </RadixTooltip.Content>
-        </RadixTooltip.Portal>
-      </RadixTooltip.Root>
-    </RadixTooltip.Provider>
-  );
-}

package/src/components/Tooltip/tooltip.types.ts

@@ -1,44 +0,0 @@
-import type { ReactNode } from 'react';
-
-export interface TooltipSlotProps {
-  content?: { className?: string };
-  arrow?: { className?: string };
-}
-
-/**
- * Props for `<Tooltip>`.
- *
- * Built on `@radix-ui/react-tooltip`. Wrap any element with a tooltip
- * that follows APG semantics (`role="tooltip"`, `aria-describedby`
- * wired to the trigger).
- *
- * Renders an arrow by default. Three side options
- * (top / right / bottom / left) with 'top' as default. Delay
- * configurable via `delayDuration` (forwarded to Radix Provider).
- */
-export interface TooltipProps {
-  /** The element that, when hovered/focused, shows the tooltip. */
-  children: ReactNode;
-  /** Tooltip body content. */
-  content: ReactNode;
-  /** Side of the trigger to show the tooltip on. @default 'top' */
-  side?: 'top' | 'right' | 'bottom' | 'left';
-  /** Alignment along the perpendicular axis. @default 'center' */
-  align?: 'start' | 'center' | 'end';
-  /** Hide the arrow indicator. @default false (arrow shown) */
-  hideArrow?: boolean;
-  /** Delay before the tooltip shows on hover (ms). @default 200 */
-  delayDuration?: number;
-  /**
-   * Controlled open state. Use when the tooltip should be programmatic
-   * (e.g. revealed on a manual button press). Omit for default
-   * hover / focus behavior.
-   */
-  open?: boolean;
-  /** Called when the tooltip's open state changes. */
-  onOpenChange?: (open: boolean) => void;
-  /** Side offset in pixels from the trigger. @default 4 */
-  sideOffset?: number;
-  /** Per-slot overrides. */
-  slotProps?: TooltipSlotProps;
-}

package/src/components/Tooltip/tooltip.variants.ts

@@ -1,28 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-export const tooltipVariants = tv({
-  slots: {
-    content: [
-      'z-50 max-w-xs rounded-md px-3 py-1.5 text-xs font-medium',
-      // Auto-invert via the dashforgePreset() CSS-var swap:
-      //  - Light mode: `bg-neutral-900` = #171717 (dark surface) +
-      //    `text-neutral-50` = #fafafa (light text) — DARK tooltip
-      //    on the light page (high contrast).
-      //  - Dark mode: `bg-neutral-900` flips to #f5f5f5 (light) +
-      //    `text-neutral-50` flips to #0a0a0a (dark text) — LIGHT
-      //    tooltip on the dark page (high contrast against page).
-      // Adding `dark:bg-neutral-50 dark:text-neutral-900` (the old
-      // pattern) would force the dark-mode tooltip back to a dark
-      // surface — invisible against the dark page.
-      'bg-neutral-900 text-neutral-50',
-      'shadow-md',
-      'data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95',
-      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
-      'motion-reduce:transition-none motion-reduce:duration-0',
-    ],
-    // Arrow tracks the content bg — auto-inverts the same way.
-    arrow: 'fill-neutral-900',
-  },
-});
-
-export type TooltipVariants = VariantProps<typeof tooltipVariants>;