@proteos/ui 0.31.0

package/src/components/data-table/states/data-table-skeleton.tsx

@@ -0,0 +1,42 @@
+import { Skeleton } from '../../skeleton'
+import { TableBody, TableCell, TableRow } from '../../table'
+
+export type DataTableSkeletonProps = {
+  rows?: number
+  columnWidths?: ReadonlyArray<number | string>
+  rowHeight?: number
+}
+
+/**
+ * Skeleton placeholder shown while the first page is loading.
+ * Renders inside the same TableBody scroller, so the layout doesn't jump
+ * when real rows replace it.
+ */
+export function DataTableSkeleton({
+  rows = 8,
+  columnWidths = [120, 240, 160, 120, 120],
+  rowHeight = 32,
+}: DataTableSkeletonProps) {
+  return (
+    <TableBody role="rowgroup" aria-label="Loading rows">
+      {Array.from({ length: rows }).map((_, rowIdx) => (
+        <TableRow
+          // biome-ignore lint/suspicious/noArrayIndexKey: deterministic placeholder rows
+          key={rowIdx}
+          alt={rowIdx % 2 === 1}
+          style={{ height: rowHeight }}
+        >
+          {columnWidths.map((w, colIdx) => (
+            <TableCell
+              // biome-ignore lint/suspicious/noArrayIndexKey: deterministic placeholder cells
+              key={colIdx}
+              width={w}
+            >
+              <Skeleton shape="text" className="h-3 max-w-[60%]" />
+            </TableCell>
+          ))}
+        </TableRow>
+      ))}
+    </TableBody>
+  )
+}

package/src/components/data-table/use-infinite-scroll-sentinel.ts

@@ -0,0 +1,51 @@
+import { type RefObject, useEffect, useRef } from 'react'
+
+export type UseInfiniteScrollSentinelOptions = {
+  onIntersect: () => void
+  /**
+   * IntersectionObserver `rootMargin`. Default `200px` so the next page
+   * starts fetching before the user scrolls all the way to the bottom.
+   */
+  rootMargin?: string
+  /**
+   * Optional scroll-container ref (passed as the observer's `root`). When
+   * omitted, the observer uses the viewport.
+   */
+  root?: Element | null
+  enabled?: boolean
+}
+
+/**
+ * Mounts a sentinel element ref. When the element scrolls into view (with
+ * the given rootMargin), `onIntersect` fires once per visible streak.
+ * Used by DataTable to drive `query.fetchNextPage()`.
+ */
+export function useInfiniteScrollSentinel<T extends Element = HTMLDivElement>({
+  onIntersect,
+  rootMargin = '200px',
+  root,
+  enabled = true,
+}: UseInfiniteScrollSentinelOptions): RefObject<T | null> {
+  const ref = useRef<T | null>(null)
+  // Latest callback in a ref so the observer doesn't re-create on every render.
+  const cbRef = useRef(onIntersect)
+  cbRef.current = onIntersect
+
+  useEffect(() => {
+    if (!enabled) return
+    const node = ref.current
+    if (!node) return
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) cbRef.current()
+        }
+      },
+      { root: root ?? null, rootMargin, threshold: 0 },
+    )
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [enabled, rootMargin, root])
+
+  return ref
+}

package/src/components/date-picker/calendar-internals.tsx

@@ -0,0 +1,138 @@
+import {
+  Button as AriaDateTrigger,
+  Calendar,
+  CalendarCell,
+  CalendarGrid,
+  CalendarGridBody,
+  CalendarGridHeader,
+  CalendarHeaderCell,
+  Heading,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+
+/* Shared calendar chrome for DatePicker + DateTimePicker. Internal — NOT
+   barrelled from the package root. Both pickers render
+   `<Popover><Dialog><CalendarSurface/>…</Dialog></Popover>`; DateTimePicker
+   additionally renders a TimeField under the grid. Keeping the icons + grid
+   here means the two pickers can never visually drift apart. */
+
+/* ----- icons (decorative) --------------------------------------------------- */
+
+export function CalendarGlyph() {
+  return (
+    <svg aria-hidden viewBox="0 0 16 16" className="size-4" fill="none">
+      <rect
+        x="2.5"
+        y="3.5"
+        width="11"
+        height="10"
+        rx="1.5"
+        stroke="currentColor"
+        strokeWidth="1.2"
+      />
+      <path d="M2.5 6.5H13.5" stroke="currentColor" strokeWidth="1.2" />
+      <path d="M5.5 2V5M10.5 2V5" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function ChevronLeft() {
+  return (
+    <svg aria-hidden viewBox="0 0 12 12" className="size-3" fill="none">
+      <path
+        d="M7.5 3L4.5 6L7.5 9"
+        stroke="currentColor"
+        strokeWidth="1.3"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+function ChevronRight() {
+  return (
+    <svg aria-hidden viewBox="0 0 12 12" className="size-3" fill="none">
+      <path
+        d="M4.5 3L7.5 6L4.5 9"
+        stroke="currentColor"
+        strokeWidth="1.3"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/* --------------------------------------------------------------------------- */
+
+/** The `<Calendar>` block — month header (prev/next + heading) plus the day
+ *  grid. Rendered inside the picker's `<Dialog>`. Cosmetics-only; the
+ *  surrounding Popover/Dialog and any TimeField are the consumer's job. */
+export function CalendarSurface() {
+  return (
+    <Calendar>
+      <header className="flex items-center justify-between mb-3">
+        <AriaDateTrigger
+          slot="previous"
+          aria-label="Previous month"
+          className={cn(
+            'size-7 rounded-md inline-flex items-center justify-center',
+            'text-ink-3 hover:text-ink hover:bg-surface-2 cursor-pointer outline-none',
+            'focus-visible:shadow-[var(--shadow-focus)]',
+          )}
+        >
+          <ChevronLeft />
+        </AriaDateTrigger>
+        <Heading className="font-sans font-medium text-[14px] text-ink tracking-[-0.01em]" />
+        <AriaDateTrigger
+          slot="next"
+          aria-label="Next month"
+          className={cn(
+            'size-7 rounded-md inline-flex items-center justify-center',
+            'text-ink-3 hover:text-ink hover:bg-surface-2 cursor-pointer outline-none',
+            'focus-visible:shadow-[var(--shadow-focus)]',
+          )}
+        >
+          <ChevronRight />
+        </AriaDateTrigger>
+      </header>
+
+      <CalendarGrid className="w-full border-collapse table-fixed">
+        <CalendarGridHeader>
+          {(day) => (
+            <CalendarHeaderCell
+              className={cn(
+                'font-mono text-[10.5px] uppercase tracking-[0.08em] text-ink-4',
+                'pb-2 text-center',
+              )}
+            >
+              {day}
+            </CalendarHeaderCell>
+          )}
+        </CalendarGridHeader>
+        <CalendarGridBody>
+          {(date) => (
+            <CalendarCell
+              date={date}
+              className={cn(
+                // aspect-square + table-fixed makes each cell a perfect
+                // square that scales with popover width.
+                'aspect-square flex items-center justify-center cursor-pointer',
+                'font-mono text-[12.5px] text-ink-2 rounded-[6px] outline-none',
+                'transition-[background-color,color] duration-150',
+                'data-[outside-month]:text-ink-4',
+                'data-[hovered]:bg-surface-2 data-[hovered]:text-ink',
+                'data-[focus-visible]:shadow-[var(--shadow-focus)]',
+                'data-[selected]:bg-accent data-[selected]:text-[#f0efe8]',
+                'data-[selected]:data-[hovered]:bg-accent-2',
+                'data-[disabled]:opacity-30 data-[disabled]:cursor-not-allowed',
+                'data-[unavailable]:line-through data-[unavailable]:text-ink-4',
+              )}
+            />
+          )}
+        </CalendarGridBody>
+      </CalendarGrid>
+    </Calendar>
+  )
+}

package/src/components/date-picker/date-picker.stories.tsx

@@ -0,0 +1,78 @@
+import { getLocalTimeZone, parseDate, today } from '@internationalized/date'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { DatePicker } from './date-picker'
+
+const meta: Meta<typeof DatePicker> = {
+  title: 'Components/DatePicker',
+  component: DatePicker,
+  tags: ['autodocs'],
+  args: {
+    label: 'Ship date',
+  },
+  argTypes: {
+    isDisabled: { control: { type: 'boolean' } },
+    isInvalid: { control: { type: 'boolean' } },
+    isReadOnly: { control: { type: 'boolean' } },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[300px]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof DatePicker>
+
+export const Playground: Story = {}
+
+export const WithValue: Story = {
+  args: {
+    defaultValue: parseDate('2026-04-24'),
+    description: 'Pre-filled with Apr 24, 2026.',
+  },
+}
+
+export const WithDescription: Story = {
+  args: {
+    description: 'When the shipment leaves the yard.',
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    isInvalid: true,
+    errorMessage: 'Pick a future date.',
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    defaultValue: parseDate('2026-04-24'),
+    isDisabled: true,
+  },
+}
+
+export const MinMax: Story = {
+  args: {
+    defaultValue: today(getLocalTimeZone()),
+    minValue: today(getLocalTimeZone()),
+    maxValue: today(getLocalTimeZone()).add({ months: 3 }),
+    description: 'Limited to the next 3 months.',
+  },
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-5 w-[300px]">
+      <DatePicker label="Rest" />
+      <DatePicker label="Selected" defaultValue={parseDate('2026-04-24')} />
+      <DatePicker label="Invalid" isInvalid errorMessage="Pick a future date." />
+      <DatePicker label="Disabled" defaultValue={parseDate('2026-04-24')} isDisabled />
+    </div>
+  ),
+}

package/src/components/date-picker/date-picker.test.tsx

@@ -0,0 +1,71 @@
+import { type CalendarDate, parseDate } from '@internationalized/date'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { DatePicker } from './date-picker'
+
+describe('DatePicker', () => {
+  it('renders a labelled date input', () => {
+    render(<DatePicker label="Ship date" />)
+    expect(screen.getByText('Ship date')).toBeInTheDocument()
+  })
+
+  it('opens the calendar popover when the trigger is clicked', async () => {
+    const user = userEvent.setup()
+    render(<DatePicker label="Ship date" />)
+
+    // The calendar-glyph trigger is the only <button> in the field (date
+    // segments are spinbuttons). When closed, it's the last <button> in the DOM.
+    const buttons = screen.getAllByRole('button')
+    const trigger = buttons[buttons.length - 1]
+    if (!trigger) throw new Error('calendar trigger missing')
+
+    await user.click(trigger)
+    expect(await screen.findByRole('application')).toBeInTheDocument()
+    expect(screen.getByRole('grid')).toBeInTheDocument()
+  })
+
+  it('selects a date and fires onChange', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(
+      <DatePicker label="Ship date" defaultValue={parseDate('2026-04-24')} onChange={onChange} />,
+    )
+
+    // Open the calendar by pressing the first non-segment button.
+    const buttons = screen.getAllByRole('button')
+    const trigger = buttons[buttons.length - 1]
+    if (!trigger) throw new Error('trigger missing')
+    await user.click(trigger)
+
+    // Click a different cell in the current (April 2026) grid — the 15th.
+    const fifteenth = await screen.findByRole('button', { name: /April 15, 2026/i })
+    await user.click(fifteenth)
+
+    expect(onChange).toHaveBeenCalled()
+    const called = onChange.mock.calls[0]?.[0] as CalendarDate | null
+    expect(called?.day).toBe(15)
+    expect(called?.month).toBe(4)
+    expect(called?.year).toBe(2026)
+  })
+
+  it('renders the error message when invalid', () => {
+    render(<DatePicker label="Ship date" isInvalid errorMessage="Pick a future date." />)
+    expect(screen.getByText('Pick a future date.')).toBeInTheDocument()
+  })
+
+  it('disables the control when isDisabled is set', () => {
+    render(<DatePicker label="Ship date" isDisabled defaultValue={parseDate('2026-04-24')} />)
+    // Every visible button in the field should be disabled.
+    const buttons = screen.getAllByRole('button')
+    for (const btn of buttons) {
+      expect(btn).toBeDisabled()
+    }
+  })
+
+  it('shows the description slot', () => {
+    render(<DatePicker label="Ship date" description="When it leaves the yard." />)
+    expect(screen.getByText('When it leaves the yard.')).toBeInTheDocument()
+  })
+})

package/src/components/date-picker/date-picker.tsx

@@ -0,0 +1,140 @@
+import type { ReactNode } from 'react'
+import {
+  DatePicker as AriaDatePicker,
+  type DatePickerProps as AriaDatePickerProps,
+  Button as AriaDateTrigger,
+  DateInput,
+  DateSegment,
+  type DateValue,
+  Dialog,
+  FieldError,
+  Group,
+  Label,
+  Popover,
+  Text,
+} from 'react-aria-components'
+import { cn } from '../../lib/cn'
+import {
+  type FieldAppearance,
+  fieldControlStyles,
+  fieldErrorStyles,
+  type FieldSize,
+  fieldHintStyles,
+  fieldLabelStyles,
+} from '../field/field'
+import { CalendarGlyph, CalendarSurface } from './calendar-internals'
+
+export type DatePickerProps<T extends DateValue> = AriaDatePickerProps<T> & {
+  label?: ReactNode
+  description?: ReactNode
+  errorMessage?: ReactNode
+  /** Field size. Defaults to `md`. */
+  size?: FieldSize
+  /** Chrome variant. Defaults to `field`. `cell` flattens the box. */
+  appearance?: FieldAppearance
+}
+
+export function DatePicker<T extends DateValue>({
+  label,
+  description,
+  errorMessage,
+  size,
+  appearance,
+  className,
+  ...props
+}: DatePickerProps<T>) {
+  const styles = fieldControlStyles({ size, appearance })
+  const focusWithin =
+    appearance === 'cell'
+      ? 'focus-within:border-accent focus-within:shadow-none'
+      : 'focus-within:border-accent focus-within:shadow-[var(--shadow-focus)]'
+  return (
+    <AriaDatePicker
+      {...props}
+      className={(renderProps) =>
+        cn(
+          'grid grid-cols-1 gap-1.5',
+          typeof className === 'function' ? className(renderProps) : className,
+        )
+      }
+    >
+      {label ? <Label className={fieldLabelStyles}>{label}</Label> : null}
+
+      <Group
+        className={cn(
+          // Box chrome on the wrapper; the DateInput inside carries padding +
+          // font so the calendar trigger sits inside the same border + ring.
+          styles.box(),
+          'flex items-center gap-1 pr-1',
+          focusWithin,
+        )}
+      >
+        <DateInput
+          className={cn(
+            'flex-1 flex items-center min-w-0 text-ink',
+            styles.content(),
+            // Tabular alignment for date segments — overrides content's
+            // font-sans on purpose.
+            'font-mono',
+          )}
+        >
+          {(segment) => (
+            <DateSegment
+              segment={segment}
+              className={cn(
+                'px-px tabular-nums outline-none select-none',
+                'data-[placeholder]:text-ink-4',
+                'data-[type=literal]:text-ink-4',
+                // segment focus treatment: indigo fill, paper text
+                'data-[focused]:bg-accent data-[focused]:text-[#f0efe8] data-[focused]:rounded-[3px]',
+                'data-[disabled]:cursor-not-allowed',
+              )}
+            />
+          )}
+        </DateInput>
+
+        <AriaDateTrigger
+          className={cn(
+            'shrink-0 inline-flex items-center justify-center',
+            'size-7 rounded-md',
+            'text-ink-3 hover:text-ink hover:bg-surface-2',
+            'outline-none cursor-pointer',
+            'focus-visible:shadow-[var(--shadow-focus)]',
+            'data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed',
+          )}
+        >
+          <CalendarGlyph />
+        </AriaDateTrigger>
+      </Group>
+
+      {description ? (
+        <Text slot="description" className={fieldHintStyles}>
+          {description}
+        </Text>
+      ) : null}
+      {errorMessage && appearance !== 'cell' ? (
+        <FieldError className={fieldErrorStyles}>{errorMessage}</FieldError>
+      ) : null}
+
+      <Popover
+        offset={6}
+        className={cn(
+          // Match the anchoring field's width exactly. `--trigger-width` is
+          // set by RAC on the Popover when it's inside a DatePicker. Floor at
+          // 18rem so the calendar stays legible when the input is unusually
+          // narrow, and cap at 600px so it doesn't sprawl behind a very wide
+          // field.
+          'w-[var(--trigger-width)] min-w-[18rem] max-w-[500px]',
+          'rounded-md border border-rule bg-surface p-4',
+          'shadow-[var(--shadow-raised)]',
+          'entering:animate-in entering:fade-in-0 entering:slide-in-from-top-1',
+          'exiting:animate-out exiting:fade-out-0 exiting:slide-out-to-top-1',
+        )}
+      >
+        <Dialog className="outline-none">
+          <CalendarSurface />
+        </Dialog>
+      </Popover>
+    </AriaDatePicker>
+  )
+}

package/src/components/date-picker/index.ts

@@ -0,0 +1,2 @@
+export type { DatePickerProps } from './date-picker'
+export { DatePicker } from './date-picker'

package/src/components/date-time-picker/date-time-picker.stories.tsx

@@ -0,0 +1,96 @@
+import { getLocalTimeZone, now, parseAbsoluteToLocal } from '@internationalized/date'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { DateTimePicker } from './date-time-picker'
+
+const meta: Meta<typeof DateTimePicker> = {
+  title: 'Components/DateTimePicker',
+  component: DateTimePicker,
+  tags: ['autodocs'],
+  args: {
+    label: 'Starts at',
+  },
+  argTypes: {
+    isDisabled: { control: { type: 'boolean' } },
+    isInvalid: { control: { type: 'boolean' } },
+    isReadOnly: { control: { type: 'boolean' } },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[320px]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof DateTimePicker>
+
+export const Playground: Story = {}
+
+export const WithValue: Story = {
+  args: {
+    defaultValue: parseAbsoluteToLocal('2026-05-04T14:30:00Z'),
+    description: 'Pre-filled — edit the time inline, or pick it in the popover.',
+  },
+}
+
+export const TwentyFourHour: Story = {
+  args: {
+    defaultValue: parseAbsoluteToLocal('2026-05-04T14:30:00Z'),
+    hourCycle: 24,
+    description: '24-hour clock.',
+  },
+}
+
+export const SecondPrecision: Story = {
+  args: {
+    defaultValue: parseAbsoluteToLocal('2026-05-04T14:30:05Z'),
+    granularity: 'second',
+    description: 'Hour : minute : second.',
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    isInvalid: true,
+    errorMessage: 'Pick a future date and time.',
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    defaultValue: now(getLocalTimeZone()),
+    isDisabled: true,
+  },
+}
+
+/** The flat, spreadsheet-style chrome used for inline table-cell editing.
+ *  The time segments are part of the inline input, so the time is editable
+ *  in-cell without opening the popover. */
+export const CellAppearance: Story = {
+  args: {
+    appearance: 'cell',
+    size: 'sm',
+    label: undefined,
+    'aria-label': 'Starts at',
+    defaultValue: parseAbsoluteToLocal('2026-05-04T14:30:00Z'),
+  },
+}
+
+export const AllStates: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => (
+    <div className="grid gap-5 w-[320px]">
+      <DateTimePicker label="Rest" />
+      <DateTimePicker label="Selected" defaultValue={parseAbsoluteToLocal('2026-05-04T14:30:00Z')} />
+      <DateTimePicker label="Invalid" isInvalid errorMessage="Pick a future date and time." />
+      <DateTimePicker
+        label="Disabled"
+        defaultValue={parseAbsoluteToLocal('2026-05-04T14:30:00Z')}
+        isDisabled
+      />
+    </div>
+  ),
+}