@hailer/mcp 1.3.14 → 1.3.23

package/.claude/skills/hailer-app-primitives/SKILL.md

@@ -0,0 +1,742 @@
+---
+name: hailer-app-primitives
+description: Canonical UI primitives for Hailer apps — load when building confirm dialogs, loading/empty/error states, searchable dropdowns, date pickers, or REST client wrappers; full source included
+version: 0.5.0
+triggers:
+  - ConfirmDialog
+  - AlertDialog
+  - LoadingState
+  - EmptyState
+  - ErrorState
+  - SearchableSelect
+  - DatePicker
+  - DateRangePicker
+  - hailerRest
+  - REST from app
+  - confirm dialog
+  - delete dialog
+  - loading state
+  - empty state
+  - searchable dropdown
+---
+
+# Hailer App Primitives
+
+Canonical UI components extracted from production apps. Copy and adapt props — do not re-derive the look. All components use Hailer Design System (Chakra UI v2 + Hailer theme). SDK-free; works in any Hailer app.
+
+**Dependency note:** `SearchableSelect` and `SearchableSelectMulti` import icons from `react-icons/fi`, which is **not** shipped by `@hailer/create-app` (neither `react-icons` nor `@chakra-ui/icons` is a template dependency — `@chakra-ui/react` does not bundle icons). Either run `npm install react-icons`, or swap in the template's bundled Hailer icons from `src/hailer/theme/icons/`: `FiChevronDown` → `HailerLargeChevronDown`, `FiX` → `HailerXSmall`, `FiCheck` → `HailerTickSmall`.
+
+**Important decision for Studio:** The hub framework auto-injects individual primitive source skills via file-pattern matching. Studio has no such injection mechanism, so **all source is inlined here**. Load this skill whenever you need any primitive.
+
+---
+
+## Built primitives
+
+| Primitive | When to use |
+|-----------|-------------|
+| **ConfirmDialog** | Destructive actions (delete, archive) and non-destructive confirmations (submit, publish) |
+| **LoadingState / EmptyState / ErrorState** | Every data-fetching view needs all three |
+| **SearchableSelect** (single) | Picking one option from a long list (> ~8 items) with keyboard nav |
+| **SearchableSelectMulti** | Filtering/tagging where the user picks several display options |
+| **DatePicker** | Single date field in forms |
+| **DateRangePicker** | Start + end date filter |
+| **dateInputToMs / toDateInputValue** | Convert between `YYYY-MM-DD` strings and Hailer's Unix-milliseconds date storage |
+| **hailerRest** | Thin authenticated REST client over `hailer.http.fetch` (v2 only) |
+
+---
+
+## ConfirmDialog
+
+A general-purpose confirm/alert dialog. Defaults to destructive-delete intent (`colorScheme="red"`) but fully configurable.
+
+**When to use:** Destructive actions (delete, archive, remove) and non-destructive confirmations (submit, publish — override `confirmColorScheme` and `confirmText`).
+
+**When NOT to use:** Form submission (use a `<form>` with a submit button), multi-step flows (use a `<Modal>` with stepper), informational alerts with no action (use `<Alert>` inline).
+
+```tsx
+import {
+  AlertDialog, AlertDialogBody, AlertDialogContent, AlertDialogFooter,
+  AlertDialogHeader, AlertDialogOverlay, Button,
+} from '@chakra-ui/react';
+import React, { useRef } from 'react';
+
+interface ConfirmDialogProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onConfirm: () => void;
+  title: string;
+  bodyText?: string;
+  cancelText?: string;
+  confirmText?: string;
+  /** Chakra colorScheme for the confirm button. Default: 'red' (destructive). */
+  confirmColorScheme?: string;
+}
+
+const ConfirmDialog: React.FC<ConfirmDialogProps> = ({
+  isOpen, onClose, onConfirm, title,
+  bodyText = 'Are you sure?',
+  cancelText = 'Cancel',
+  confirmText = 'Delete',
+  confirmColorScheme = 'red',
+}) => {
+  const cancelRef = useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <AlertDialog isOpen={isOpen} leastDestructiveRef={cancelRef} onClose={onClose} isCentered>
+      <AlertDialogOverlay>
+        <AlertDialogContent>
+          <AlertDialogHeader>{title}</AlertDialogHeader>
+          <AlertDialogBody>{bodyText}</AlertDialogBody>
+          <AlertDialogFooter>
+            <Button ref={cancelRef} onClick={onClose}>{cancelText}</Button>
+            <Button colorScheme={confirmColorScheme} onClick={onConfirm} ml={3}>
+              {confirmText}
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialogOverlay>
+    </AlertDialog>
+  );
+};
+
+export default ConfirmDialog;
+```
+
+**Props:**
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `isOpen` | `boolean` | — | Required |
+| `onClose` | `() => void` | — | Required |
+| `onConfirm` | `() => void` | — | Required |
+| `title` | `string` | — | Required |
+| `bodyText` | `string` | `'Are you sure?'` | |
+| `cancelText` | `string` | `'Cancel'` | |
+| `confirmText` | `string` | `'Delete'` | |
+| `confirmColorScheme` | `string` | `'red'` | Use `'green'` for non-destructive |
+
+**Usage:**
+
+```tsx
+// Destructive delete (defaults)
+<ConfirmDialog
+  isOpen={isDeleteOpen}
+  onClose={onDeleteClose}
+  onConfirm={handleDelete}
+  title="Poista rivi"
+  bodyText="Haluatko varmasti poistaa tämän rivin? Toimintoa ei voi peruuttaa."
+  confirmText="Poista"
+/>
+
+// Non-destructive confirm
+<ConfirmDialog
+  isOpen={isSubmitOpen}
+  onClose={onSubmitClose}
+  onConfirm={handleSubmit}
+  title="Lähetä lomake"
+  bodyText="Haluatko lähettää lomakkeen?"
+  confirmText="Lähetä"
+  confirmColorScheme="green"
+/>
+
+// State pattern (pair with useDisclosure):
+const { isOpen, onOpen, onClose } = useDisclosure();
+<Button colorScheme="red" onClick={onOpen}>Poista</Button>
+<ConfirmDialog
+  isOpen={isOpen}
+  onClose={onClose}
+  onConfirm={() => { handleDelete(); onClose(); }}
+  title="Poista kohde"
+/>
+```
+
+---
+
+## LoadingState / EmptyState / ErrorState
+
+Three composable state-feedback components. Every data-fetching view needs all three.
+
+```tsx
+import { Box, Button, Spinner, Text, VStack } from '@chakra-ui/react';
+import React from 'react';
+
+// ── LoadingState ──────────────────────────────────────────────────────────────
+
+interface LoadingStateProps {
+  /** Label shown below the spinner. Default: 'Ladataan…' */
+  label?: string;
+}
+
+export function LoadingState({ label = 'Ladataan…' }: LoadingStateProps) {
+  return (
+    <Box py={12} textAlign="center">
+      <VStack spacing={3}>
+        <Spinner size="xl" color="green.500" thickness="3px" />
+        <Text color="subtleText" fontSize="sm">{label}</Text>
+      </VStack>
+    </Box>
+  );
+}
+
+// ── EmptyState ────────────────────────────────────────────────────────────────
+
+interface EmptyStateProps {
+  /** Main message. Default: 'Ei tietoja näytettäväksi' */
+  label?: string;
+  /** Optional icon or illustration above the label. */
+  icon?: React.ReactNode;
+}
+
+export function EmptyState({ label = 'Ei tietoja näytettäväksi', icon }: EmptyStateProps) {
+  return (
+    <Box py={12} textAlign="center">
+      <VStack spacing={3}>
+        {icon}
+        <Text color="subtleText" fontSize="md">{label}</Text>
+      </VStack>
+    </Box>
+  );
+}
+
+// ── ErrorState ────────────────────────────────────────────────────────────────
+
+interface ErrorStateProps {
+  /** Error message to display. */
+  message: string;
+  /** Optional retry callback. When provided, a retry button is rendered. */
+  onRetry?: () => void;
+  /** Retry button label. Default: 'Yritä uudelleen' */
+  retryLabel?: string;
+}
+
+export function ErrorState({ message, onRetry, retryLabel = 'Yritä uudelleen' }: ErrorStateProps) {
+  return (
+    <Box p={8} textAlign="center">
+      <Text color="red.500" mb={3}>{message}</Text>
+      {onRetry && (
+        <Button colorScheme="gray" size="sm" onClick={onRetry}>{retryLabel}</Button>
+      )}
+    </Box>
+  );
+}
+```
+
+**Usage:**
+
+```tsx
+if (isLoading) return <LoadingState />;
+if (error) return <ErrorState message={error.message} onRetry={refetch} />;
+if (!items.length) return <EmptyState label="Ei tilauksia löytynyt" />;
+```
+
+**Note:** `color="green.500"` matches the Hailer brand. Do not use `color="blue.500"` for the spinner.
+
+---
+
+## SearchableSelect (single)
+
+Combobox-style dropdown with inline search, keyboard navigation (↑↓ Enter Esc), optional badge, and optional clear button.
+
+**When to use:** Picking one option from a long list (> ~8 items).
+**When NOT to use:** Short lists (≤ 8 items) — use Chakra `<Select>` or `<RadioGroup>`.
+
+```tsx
+import { useState, useRef, useEffect, useMemo, useCallback, KeyboardEvent } from 'react';
+import {
+  Box, HStack, IconButton, Input, InputGroup, InputRightElement,
+  Popover, PopoverBody, PopoverContent, PopoverTrigger, Text, useColorModeValue,
+} from '@chakra-ui/react';
+import { FiChevronDown, FiX } from 'react-icons/fi';
+
+export interface SelectOption {
+  _id: string;
+  name: string;
+  badge?: string;
+}
+
+interface SearchableSelectProps {
+  value: string | null;
+  onChange: (id: string) => void;
+  options: SelectOption[];
+  placeholder: string;
+  isDisabled?: boolean;
+  isInvalid?: boolean;
+  allowClear?: boolean;
+}
+
+export default function SearchableSelect({
+  value, onChange, options, placeholder,
+  isDisabled = false, isInvalid = false, allowClear = false,
+}: SearchableSelectProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const [highlightIndex, setHighlightIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const selectedOption = useMemo(() => options.find((o) => o._id === value) ?? null, [options, value]);
+  const filtered = useMemo(() => {
+    if (!search.trim()) return options;
+    const q = search.toLowerCase();
+    return options.filter((o) => o.name.toLowerCase().includes(q));
+  }, [options, search]);
+
+  useEffect(() => { setHighlightIndex(0); }, [search, isOpen]);
+  useEffect(() => {
+    if (!isOpen || !listRef.current) return;
+    const el = listRef.current.querySelector<HTMLElement>(`[data-option-index="${highlightIndex}"]`);
+    if (el) el.scrollIntoView({ block: 'nearest' });
+  }, [highlightIndex, isOpen]);
+
+  const open = useCallback(() => {
+    if (isDisabled) return;
+    setIsOpen(true); setSearch('');
+    setTimeout(() => inputRef.current?.focus(), 0);
+  }, [isDisabled]);
+  const close = useCallback(() => { setIsOpen(false); setSearch(''); }, []);
+  const select = useCallback((id: string) => { onChange(id); close(); }, [onChange, close]);
+
+  const handleKeyDown = useCallback((e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Escape') { e.preventDefault(); close(); return; }
+    if (e.key === 'ArrowDown') { e.preventDefault(); setHighlightIndex((i) => Math.min(i + 1, Math.max(0, filtered.length - 1))); return; }
+    if (e.key === 'ArrowUp') { e.preventDefault(); setHighlightIndex((i) => Math.max(0, i - 1)); return; }
+    if (e.key === 'Enter') { e.preventDefault(); const opt = filtered[highlightIndex]; if (opt) select(opt._id); return; }
+  }, [filtered, highlightIndex, select, close]);
+
+  const triggerBg = useColorModeValue('white', 'gray.700');
+  const triggerBorder = useColorModeValue(isInvalid ? 'red.500' : 'gray.200', isInvalid ? 'red.300' : 'gray.600');
+  const hoverBg = useColorModeValue('gray.100', 'gray.600');
+  const highlightBg = useColorModeValue('green.50', 'green.900');
+  const placeholderColor = useColorModeValue('gray.500', 'gray.400');
+
+  return (
+    <Popover isOpen={isOpen} onClose={close} placement="bottom-start" autoFocus={false} matchWidth isLazy>
+      <PopoverTrigger>
+        <HStack
+          as="button" type="button" onClick={() => (isOpen ? close() : open())}
+          spacing={0} w="100%" h="40px" px={3}
+          bg={triggerBg} border="1px solid" borderColor={triggerBorder} borderRadius="md"
+          cursor={isDisabled ? 'not-allowed' : 'pointer'} opacity={isDisabled ? 0.6 : 1}
+          _hover={{ borderColor: isDisabled ? triggerBorder : 'gray.300' }} textAlign="left"
+        >
+          <Text flex={1} noOfLines={1} color={selectedOption ? undefined : placeholderColor} fontSize="md">
+            {selectedOption ? selectedOption.name : placeholder}
+          </Text>
+          {selectedOption?.badge && <Text fontSize="sm" color="subtleText" mr={2}>{selectedOption.badge}</Text>}
+          {allowClear && selectedOption && !isDisabled && (
+            <IconButton icon={<FiX />} aria-label="Tyhjennä valinta" size="xs" variant="ghost"
+              onClick={(e) => { e.stopPropagation(); onChange(''); }} mr={1} />
+          )}
+          <Box color="gray.500"><FiChevronDown /></Box>
+        </HStack>
+      </PopoverTrigger>
+      <PopoverContent w="100%">
+        <PopoverBody p={2}>
+          <InputGroup size="sm" mb={2}>
+            <Input ref={inputRef} placeholder="Hae..." value={search}
+              onChange={(e) => setSearch(e.target.value)} onKeyDown={handleKeyDown} autoFocus />
+            {search && (
+              <InputRightElement>
+                <IconButton icon={<FiX />} aria-label="Tyhjennä haku" size="xs" variant="ghost" onClick={() => setSearch('')} />
+              </InputRightElement>
+            )}
+          </InputGroup>
+          <Box ref={listRef} maxH="240px" overflowY="auto">
+            {filtered.length === 0 ? (
+              <Text fontSize="sm" color="subtleText" p={2}>Ei tuloksia</Text>
+            ) : (
+              filtered.map((opt, idx) => (
+                <HStack key={opt._id} data-option-index={idx} px={3} py={2} borderRadius="md" cursor="pointer"
+                  bg={idx === highlightIndex ? highlightBg : 'transparent'} _hover={{ bg: hoverBg }}
+                  onClick={() => select(opt._id)} spacing={2}>
+                  <Text flex={1} fontSize="sm" noOfLines={1}>{opt.name}</Text>
+                  {opt.badge && <Text fontSize="xs" color="subtleText">{opt.badge}</Text>}
+                </HStack>
+              ))
+            )}
+          </Box>
+        </PopoverBody>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+**Usage:**
+
+```tsx
+const [selectedId, setSelectedId] = useState<string | null>(null);
+const options = activities.map(a => ({ _id: a._id, name: a.name }));
+
+<SearchableSelect
+  value={selectedId}
+  onChange={setSelectedId}
+  options={options}
+  placeholder="Valitse projekti..."
+  allowClear
+/>
+```
+
+---
+
+## SearchableSelectMulti
+
+Multi-select combobox. Shows tags for 1–2 selected, count label for 3+. Stays open for multi-pick.
+
+**Important:** Hailer has no multi-select field type. This is a pure UI affordance — map each selected value to separate Hailer field writes when saving.
+
+```tsx
+import { useState, useRef, useMemo } from 'react';
+import {
+  Box, HStack, IconButton, Input, InputGroup, InputRightElement,
+  List, ListItem, Popover, PopoverAnchor, PopoverContent,
+  Tag, TagCloseButton, TagLabel, Text, useColorModeValue, useDisclosure, Wrap, WrapItem,
+} from '@chakra-ui/react';
+import { FiCheck, FiChevronDown, FiX } from 'react-icons/fi';
+
+interface SearchableSelectMultiProps {
+  placeholder: string;
+  options: string[];
+  value: string[];
+  onChange: (value: string[]) => void;
+  maxW?: string;
+}
+
+export default function SearchableSelectMulti({
+  placeholder, options, value, onChange, maxW = '280px',
+}: SearchableSelectMultiProps) {
+  const { isOpen, onOpen, onClose } = useDisclosure();
+  const [search, setSearch] = useState('');
+  const inputRef = useRef<HTMLInputElement>(null);
+  const selectedSet = useMemo(() => new Set(value), [value]);
+  const filtered = useMemo(() => {
+    if (!search) return options;
+    const lower = search.toLowerCase();
+    return options.filter((opt) => opt.toLowerCase().includes(lower));
+  }, [options, search]);
+
+  const hoverBg = useColorModeValue('gray.100', 'gray.600');
+  const selectedBg = useColorModeValue('green.50', 'rgba(72, 187, 120, 0.12)');
+  const popBg = useColorModeValue('white', 'gray.700');
+  const borderColor = useColorModeValue('gray.200', 'gray.600');
+  const tickColor = useColorModeValue('green.500', 'green.300');
+
+  const handleToggle = (opt: string) => {
+    onChange(selectedSet.has(opt) ? value.filter((v) => v !== opt) : [...value, opt]);
+  };
+  const handleClear = () => { onChange([]); setSearch(''); onClose(); };
+  const handleRemoveTag = (opt: string) => onChange(value.filter((v) => v !== opt));
+
+  const triggerContent = () => {
+    if (value.length === 0) return null;
+    if (value.length <= 2) {
+      return (
+        <Wrap spacing={1} overflow="hidden" maxW="calc(100% - 28px)">
+          {value.map((v) => (
+            <WrapItem key={v}>
+              <Tag size="sm" colorScheme="green" variant="subtle" borderRadius="full">
+                <TagLabel fontSize="xs" maxW="100px" isTruncated>{v}</TagLabel>
+                <TagCloseButton onClick={(e) => { e.stopPropagation(); handleRemoveTag(v); }} />
+              </Tag>
+            </WrapItem>
+          ))}
+        </Wrap>
+      );
+    }
+    return <Text fontSize="sm" color="bodyText" isTruncated>{value.length} valittu</Text>;
+  };
+
+  return (
+    <Popover isOpen={isOpen} onClose={onClose} autoFocus={false} matchWidth placement="bottom-start">
+      <PopoverAnchor>
+        <Box maxW={maxW} minW="180px">
+          {isOpen ? (
+            <InputGroup size="sm">
+              <Input ref={inputRef} placeholder="Hae..." value={search}
+                onChange={(e) => { setSearch(e.target.value); if (!isOpen) onOpen(); }}
+                onFocus={() => { setSearch(''); onOpen(); }}
+                onBlur={() => setTimeout(() => { setSearch(''); onClose(); }, 150)}
+                autoComplete="off" />
+              <InputRightElement w="auto" pr={1}>
+                {value.length > 0 ? (
+                  <IconButton aria-label="Tyhjennä" icon={<FiX />} size="xs" variant="ghost" onClick={handleClear} tabIndex={-1} />
+                ) : (
+                  <Box as={FiChevronDown} boxSize={4} color="gray.400" mr={1} />
+                )}
+              </InputRightElement>
+            </InputGroup>
+          ) : (
+            <HStack as="button" type="button"
+              onClick={() => { onOpen(); setTimeout(() => inputRef.current?.focus(), 0); }}
+              h="32px" px={3} w="100%" borderWidth="1px" borderColor={borderColor} borderRadius="md"
+              bg="transparent" cursor="pointer" spacing={1}
+              _hover={{ borderColor: 'gray.300' }} justify="space-between" align="center" overflow="hidden">
+              {value.length === 0
+                ? <Text fontSize="sm" color="subtleText" isTruncated>{placeholder}</Text>
+                : triggerContent()}
+              {value.length > 0 ? (
+                <IconButton aria-label="Tyhjennä" icon={<FiX />} size="xs" variant="ghost"
+                  onClick={(e) => { e.stopPropagation(); handleClear(); }} tabIndex={-1} flexShrink={0} />
+              ) : (
+                <Box as={FiChevronDown} boxSize={4} color="gray.400" flexShrink={0} />
+              )}
+            </HStack>
+          )}
+        </Box>
+      </PopoverAnchor>
+      <PopoverContent w="100%" maxH="280px" overflowY="auto" border="1px solid" borderColor={borderColor}
+        bg={popBg} shadow="md" borderRadius="md" p={0} _focus={{ outline: 'none' }}>
+        <List spacing={0}>
+          {value.length > 0 && (
+            <ListItem px={3} py={1.5} fontSize="sm" cursor="pointer" color="red.500" fontWeight="medium"
+              _hover={{ bg: hoverBg }} onMouseDown={(e) => { e.preventDefault(); handleClear(); }}>
+              Tyhjennä valinnat
+            </ListItem>
+          )}
+          {filtered.length === 0 && (
+            <ListItem px={3} py={2}><Text fontSize="sm" color="subtleText">Ei tuloksia</Text></ListItem>
+          )}
+          {filtered.map((opt) => {
+            const isSelected = selectedSet.has(opt);
+            return (
+              <ListItem key={opt} px={3} py={1.5} fontSize="sm" cursor="pointer"
+                bg={isSelected ? selectedBg : undefined} _hover={{ bg: isSelected ? selectedBg : hoverBg }}
+                display="flex" alignItems="center" justifyContent="space-between"
+                onMouseDown={(e) => { e.preventDefault(); handleToggle(opt); }}>
+                <Text isTruncated>{opt}</Text>
+                {isSelected && <Box as={FiCheck} boxSize={4} color={tickColor} flexShrink={0} ml={2} />}
+              </ListItem>
+            );
+          })}
+        </List>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+**Usage:**
+
+```tsx
+const [selectedTypes, setSelectedTypes] = useState<string[]>([]);
+
+<SearchableSelectMulti
+  value={selectedTypes}
+  onChange={setSelectedTypes}
+  options={['Toimitus', 'Nouto', 'Palautus', 'Varastointi']}
+  placeholder="Kaikki tyypit"
+/>
+```
+
+---
+
+## DatePicker / DateRangePicker
+
+Native browser `<input type="date">` — no external calendar library needed.
+
+**When to use:** Date fields in forms (single date), date range filters.
+**When NOT to use:** Monthly/weekly calendar grid with events (use FullCalendar instead).
+
+```tsx
+import { Box, FormControl, FormLabel, HStack, Input, Text } from '@chakra-ui/react';
+import React from 'react';
+
+// ── DatePicker ────────────────────────────────────────────────────────────────
+
+interface DatePickerProps {
+  label?: string;
+  value: string;            // YYYY-MM-DD
+  onChange: (value: string) => void;
+  min?: string;             // YYYY-MM-DD
+  max?: string;             // YYYY-MM-DD
+  isDisabled?: boolean;
+  isRequired?: boolean;
+  isInvalid?: boolean;
+}
+
+export function DatePicker({ label, value, onChange, min, max, isDisabled = false, isRequired = false, isInvalid = false }: DatePickerProps) {
+  return (
+    <FormControl isDisabled={isDisabled} isRequired={isRequired} isInvalid={isInvalid}>
+      {label && <FormLabel>{label}</FormLabel>}
+      <Input type="date" value={value} onChange={(e) => onChange(e.target.value)} min={min} max={max} />
+    </FormControl>
+  );
+}
+
+// ── DateRangePicker ───────────────────────────────────────────────────────────
+
+interface DateRangePickerProps {
+  startLabel?: string;
+  endLabel?: string;
+  startValue: string;       // YYYY-MM-DD
+  endValue: string;         // YYYY-MM-DD
+  onStartChange: (value: string) => void;
+  onEndChange: (value: string) => void;
+  isDisabled?: boolean;
+}
+
+export function DateRangePicker({
+  startLabel = 'Alkaa', endLabel = 'Päättyy',
+  startValue, endValue, onStartChange, onEndChange, isDisabled = false,
+}: DateRangePickerProps) {
+  return (
+    <HStack spacing={3} align="flex-end" wrap="wrap">
+      <DatePicker label={startLabel} value={startValue}
+        onChange={(v) => { onStartChange(v); if (endValue && v && endValue < v) onEndChange(v); }}
+        max={endValue || undefined} isDisabled={isDisabled} />
+      <Text pb={2} color="subtleText">–</Text>
+      <DatePicker label={endLabel} value={endValue} onChange={onEndChange}
+        min={startValue || undefined} isDisabled={isDisabled} />
+    </HStack>
+  );
+}
+```
+
+## Date ↔ ms conversion helpers
+
+Hailer date fields store **Unix milliseconds** (`number`) — confirmed by the API validation schema (`hailer-api/src/validation/sharedSchemas.ts`: `JoiDate` = "milliseconds since 1970-01-01 UTC"). Convert when reading/writing:
+
+```ts
+/** 'YYYY-MM-DD' → Unix milliseconds */
+export const dateInputToMs = (v: string): number =>
+  v ? new Date(v).getTime() : 0;
+
+/** Unix milliseconds → 'YYYY-MM-DD' */
+export const toDateInputValue = (ms: number): string =>
+  ms ? new Date(ms).toISOString().slice(0, 10) : '';
+```
+
+**Usage:**
+
+```tsx
+const [date, setDate] = useState('');
+const [startDate, setStartDate] = useState('');
+const [endDate, setEndDate] = useState('');
+
+<DatePicker
+  label="Toimituspäivä"
+  value={date}
+  onChange={setDate}
+  min={toDateInputValue(Date.now())}
+/>
+
+<DateRangePicker
+  startValue={startDate} endValue={endDate}
+  onStartChange={setStartDate} onEndChange={setEndDate}
+/>
+
+// Save to Hailer — update takes an ARRAY of {_id, fields}, then options
+hailer.activity.update([
+  { _id: activityId, fields: { [FIELDS.deliveryDate]: dateInputToMs(date) } }
+], {});
+```
+
+---
+
+## hailerRest — REST client primitive
+
+Thin wrapper over `hailer.http.fetch` (app-sdk v2) that handles URL building, JSON body parsing, and error normalisation.
+
+**v2 only.** `hailer.http` does not exist on app-sdk v1. Check `package.json` before using.
+
+### Verified signature (from `@hailer/app-sdk` v2 `.d.ts`)
+
+```ts
+// HTTPFetchOptions
+interface HTTPFetchOptions {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;              // always a string — stringify before passing
+}
+
+// HTTPFetchResponse — body is a RAW STRING, not parsed JSON
+interface HTTPFetchResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: string;
+}
+```
+
+### Source
+
+```ts
+const API_BASE = 'https://api.hailer.com';
+
+export interface HailerRestError extends Error {
+  status?: number;
+  body?: unknown;
+}
+
+export async function hailerRest<T = unknown>(
+  hailer: HailerApi,              // the app-sdk v2 instance
+  path: string,                   // '/api/v3/activity.list' or a full api.hailer.com URL
+  opts: {
+    method?: string;
+    body?: unknown;               // object → JSON.stringify'd
+    headers?: Record<string, string>;
+  } = {},
+): Promise<T> {
+  const url = path.startsWith('http') ? path : `${API_BASE}${path}`;
+
+  const res = await hailer.http.fetch(url, {
+    method: opts.method ?? (opts.body !== undefined ? 'POST' : 'GET'),
+    headers: { 'Content-Type': 'application/json', ...opts.headers },
+    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+  });
+
+  let parsed: unknown;
+  try { parsed = res.body ? JSON.parse(res.body) : null; }
+  catch { parsed = res.body; }    // non-JSON (e.g. an nginx 403 HTML page)
+
+  if (res.status < 200 || res.status >= 300) {
+    const err = new Error(
+      `hailerRest ${res.status} ${res.statusText} — ${path}`
+    ) as HailerRestError;
+    err.status = res.status;
+    err.body = parsed;
+    throw err;
+  }
+
+  return parsed as T;
+}
+```
+
+**Usage:**
+
+```ts
+// Fetch activities from a workflow
+const result = await hailerRest(hailer, '/api/v3/activity.list', {
+  body: { processId, filter: { phaseId } },
+});
+
+// Explicit method
+const updated = await hailerRest(hailer, `/api/v3/activity.update`, {
+  method: 'POST',
+  body: { activityId, fields: { [fieldId]: value } },
+});
+```
+
+**Platform requirements:**
+- **Web:** Works out-of-the-box. `api.hailer.com` is on the global allowlist.
+- **iOS:** Requires `https://api.hailer.com` in the app's `allowedUrls` config. Default is empty → 400 "URL not allowed".
+
+**Security note:** `hailer.http.fetch` runs as the **current user** — app-side filtering is not an isolation boundary. Elevated privileges or cross-user access belongs in a server-side microservice.
+
+---
+
+## Planned primitives (not yet extracted)
+
+Candidates from the app fleet. Use existing app implementations as reference until a primitive lands:
+
+- **Stepper / wizard** — 3 independent variants (StepperBar, PhasePipeline, StepIndicator)
+- **Toolbar / FilterBar** — pairs with calendar and list views
+- **Stat / KPI card** — 4 dashboard variants (SummaryCard, KPICards, KpiTile, CountWidget)
+- **StatusBadge** — phase → colored badge
+- **Drawer** (detail / side panel) — generic Chakra wrappers
+- **TimeInput** — auto-format HH:MM
+- **DataTable + states / skeleton** — table-with-loading/empty + configurable skeleton
+
+## Calendar — deferred
+
+Both production CalendarToolbar variants wrap FullCalendar + Bootstrap, not Chakra. Use [FullCalendar](https://fullcalendar.io/) (`@fullcalendar/react`) for calendar grid views. Use `DateRangePicker` for date range inputs that don't need a grid view.