fermmap-shared 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,693 @@
+import { ButtonProps as _ButtonProps1, TextFieldProps as _TextFieldProps1, Selection, CheckboxProps as _CheckboxProps1, Key, SortDescriptor, DisclosureGroupProps, LinkProps, RadioGroupProps as _RadioGroupProps1, SelectProps, SwitchProps as _SwitchProps1, TabListProps, TabPanelProps, TabProps, TabsProps } from "react-aria-components";
+import { JSX } from "react/jsx-runtime";
+import { ReactNode } from "react";
+interface ButtonProps extends _ButtonProps1 {
+    children?: React.ReactNode;
+    variant?: 'primary' | 'secondary' | 'danger' | 'navigation';
+    size?: 'S' | 'M' | 'L';
+}
+export const Button: ({ children, variant, size, className, ...props }: ButtonProps) => JSX.Element;
+export const textFieldInputStyles: () => {
+    readonly padding: 12;
+    readonly paddingX: 16;
+    readonly borderWidth: 1;
+    readonly borderStyle: "solid";
+    readonly borderColor: {
+        readonly default: "--plum-300";
+        readonly isHovered: "--plum-400";
+        readonly isFocusVisible: "--plum-500";
+        readonly isInvalid: "--berry-500";
+    };
+    readonly borderRadius: "lg";
+    readonly font: "body";
+    readonly backgroundColor: "layer-1";
+    readonly color: "neutral";
+    readonly outline: "none";
+};
+interface TextFieldProps extends Omit<_TextFieldProps1, 'children'> {
+    label: string;
+    type?: 'text' | 'password' | 'email' | 'tel' | 'url' | 'number';
+    error?: string;
+    description?: string;
+    placeholder?: string;
+}
+export function TextField({ label, type, error, description, placeholder, ...props }: TextFieldProps): JSX.Element;
+interface AlertDialogProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    message: string;
+    variant?: 'danger' | 'warning' | 'info' | 'success';
+    confirmLabel?: string;
+    cancelLabel?: string;
+    onConfirm: () => void | Promise<void>;
+    showCancel?: boolean;
+    children?: React.ReactNode;
+}
+export function AlertDialog({ isOpen, onClose, title, message, variant, confirmLabel, cancelLabel, onConfirm, showCancel, children }: AlertDialogProps): JSX.Element;
+interface PromptDialogProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    message: string;
+    inputLabel: string;
+    inputPlaceholder?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    onConfirm: (value: string) => void | Promise<void>;
+    validator?: (value: string) => string | null;
+}
+export function PromptDialog({ isOpen, onClose, title, message, inputLabel, inputPlaceholder, confirmLabel, cancelLabel, onConfirm, validator }: PromptDialogProps): JSX.Element;
+export interface AutocompleteItem {
+    id: string | number;
+    name: string;
+    [key: string]: any;
+}
+export interface AutocompleteProps<T extends AutocompleteItem> {
+    items: T[];
+    selectedKeys?: Selection;
+    onSelectionChange?: (keys: Selection) => void;
+    selectionMode?: 'none' | 'single' | 'multiple';
+    label: string;
+    placeholder?: string;
+    ariaLabel?: string;
+    error?: string;
+    getItemText?: (item: T) => string;
+}
+/**
+ * Autocomplete component using React Aria SearchField + ListBox
+ *
+ * Features:
+ * - SearchField for filtering items
+ * - Optional checkboxes for multi-selection
+ * - Shows both selected and unselected items when filtered
+ * - Selected items highlighted with background color
+ * - Keyboard navigation (arrow keys, enter, escape)
+ * - Accessible (ARIA labels, focus management)
+ *
+ * @example
+ * ```tsx
+ * // Single select
+ * <Autocomplete
+ *   items={sources}
+ *   selectedKeys={selectedKey}
+ *   onSelectionChange={setSelectedKey}
+ *   selectionMode="single"
+ *   label="Select Source"
+ *   placeholder="Search sources..."
+ * />
+ *
+ * // Multi select
+ * <Autocomplete
+ *   items={sources}
+ *   selectedKeys={selectedKeys}
+ *   onSelectionChange={setSelectedKeys}
+ *   selectionMode="multiple"
+ *   label="Select Sources"
+ *   placeholder="Search sources..."
+ * />
+ *
+ * // No selection (just filtering)
+ * <Autocomplete
+ *   items={sources}
+ *   selectionMode="none"
+ *   label="Search Sources"
+ *   placeholder="Search sources..."
+ * />
+ * ```
+ */
+export function Autocomplete<T extends AutocompleteItem>({ items, selectedKeys, onSelectionChange, selectionMode, label, placeholder, ariaLabel, error, getItemText, }: AutocompleteProps<T>): JSX.Element;
+export interface CheckboxProps extends Omit<_CheckboxProps1, 'className' | 'style'> {
+    /**
+     * The size of the Checkbox.
+     * @default 'M'
+     */
+    size?: 'S' | 'M' | 'L';
+}
+/**
+ * Checkbox component for selection within tables and forms.
+ * Simplified version based on React Spectrum S2 Checkbox.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox isSelected={selected} onChange={setSelected}>
+ *   Subscribe to newsletter
+ * </Checkbox>
+ *
+ * // In table header/cell (no label)
+ * <Checkbox slot="selection" />
+ * ```
+ */
+export function Checkbox({ size, children, ...props }: CheckboxProps): JSX.Element;
+interface ProgressBarProps {
+    label?: string;
+    value?: number;
+    maxValue?: number;
+    isIndeterminate?: boolean;
+    showValueLabel?: boolean;
+    'aria-label'?: string;
+}
+/**
+ * ProgressBar Component
+ *
+ * Accessible progress indicator using React Aria Components.
+ * Supports both determinate (with value) and indeterminate (loading) states.
+ *
+ * @example
+ * // Determinate progress
+ * <ProgressBar label="Loading..." value={50} maxValue={100} />
+ *
+ * @example
+ * // Indeterminate progress
+ * <ProgressBar label="Loading..." isIndeterminate />
+ */
+export function ProgressBar({ label, value, maxValue, isIndeterminate, showValueLabel, 'aria-label': ariaLabel, }: ProgressBarProps): JSX.Element;
+export interface ColumnDef<T> {
+    key: string;
+    label: string;
+    renderCell: (item: T) => ReactNode;
+    width?: string;
+    isRowHeader?: boolean;
+    align?: 'start' | 'center' | 'end';
+}
+export interface TableProps<T> {
+    data: T[];
+    columns: ColumnDef<T>[];
+    onRowAction?: (key: Key) => void;
+    ariaLabel: string;
+    sortDescriptor?: SortDescriptor;
+    onSortChange?: (descriptor: SortDescriptor) => void;
+    selectionMode?: 'none' | 'single' | 'multiple';
+    selectedKeys?: Set<Key>;
+    onSelectionChange?: (keys: Set<Key>) => void;
+    onLoadMore?: () => void;
+    isLoadingMore?: boolean;
+}
+/**
+ * Reusable Table component using React Aria Components
+ *
+ * Features:
+ * - Collection-based API for better performance
+ * - Built-in virtualization support (via RAC)
+ * - Keyboard navigation
+ * - Screen reader support
+ * - Optional sorting
+ * - Optional row selection
+ * - Optional row actions (clickable rows)
+ * - Checkbox column for multiple selection
+ * - Hover and selected states
+ *
+ * @example
+ * ```tsx
+ * const columns: ColumnDef<Run>[] = [
+ *   { key: 'id', label: 'ID', renderCell: (run) => `#${run.id}` },
+ *   { key: 'status', label: 'Status', renderCell: (run) => <Badge variant={run.status}>{run.status}</Badge> }
+ * ];
+ *
+ * <Table
+ *   data={runs}
+ *   columns={columns}
+ *   ariaLabel="Scraper runs"
+ *   selectionMode="multiple"
+ *   selectedKeys={selectedIds}
+ *   onSelectionChange={setSelectedIds}
+ * />
+ * ```
+ */
+export function Table<T extends {
+    id: number | string;
+}>({ data, columns, onRowAction, ariaLabel, sortDescriptor, onSortChange, selectionMode, selectedKeys, onSelectionChange, onLoadMore, isLoadingMore }: TableProps<T>): JSX.Element;
+export interface AutocompleteTableProps<T extends AutocompleteItem> {
+    allItems: T[];
+    selectedKeys: Selection;
+    onSelectionChange: (keys: Selection) => void;
+    selectionMode?: 'single' | 'multiple';
+    searchLabel: string;
+    searchPlaceholder?: string;
+    getItemText?: (item: T) => string;
+    columns: ColumnDef<T>[];
+    tableLabel: string;
+}
+/**
+ * Composite component combining Autocomplete and Table
+ * Useful for search-and-select workflows where selected items are displayed in a table
+ *
+ * Features:
+ * - Autocomplete search field at top
+ * - Table below showing selected items
+ * - Filters all items in autocomplete
+ * - Shows only selected items in table
+ * - Scrollable table with max height of 384px
+ *
+ * @example
+ * ```tsx
+ * <AutocompleteTable
+ *   allItems={allSources}
+ *   selectedKeys={selectedSourceIds}
+ *   onSelectionChange={setSelectedSourceIds}
+ *   selectionMode="multiple"
+ *   searchLabel="Search Sources"
+ *   searchPlaceholder="Search by name or URL..."
+ *   columns={[
+ *     { key: 'name', label: 'Name', isRowHeader: true },
+ *     { key: 'domain', label: 'Domain' },
+ *     { key: 'actions', label: 'Actions', align: 'end' },
+ *   ]}
+ *   tableLabel="Selected Sources"
+ * />
+ * ```
+ */
+export function AutocompleteTable<T extends AutocompleteItem>({ allItems, selectedKeys, onSelectionChange, selectionMode, searchLabel, searchPlaceholder, getItemText, columns, tableLabel, }: AutocompleteTableProps<T>): JSX.Element;
+export type BadgeVariant = 'completed' | 'running' | 'failed' | 'cancelled' | 'pending' | 'plum' | 'cucumber' | 'berry' | 'ginger' | 'peach';
+interface BadgeProps {
+    variant?: BadgeVariant;
+    children: React.ReactNode;
+}
+/**
+ * Badge component for displaying status or category with conditional colors
+ *
+ * @example
+ * <Badge variant="completed">Completed</Badge>
+ * <Badge variant="cucumber">Vegetable</Badge>
+ */
+export function Badge({ variant, children }: BadgeProps): JSX.Element;
+type LocaleMessages = Record<string, Record<string, string>>;
+interface I18nProviderProps {
+    children: ReactNode;
+    messages: LocaleMessages;
+}
+/**
+ * Unified i18n provider that can be used by both frontend and admin UI.
+ *
+ * @param messages - Locale messages object (e.g., from src/i18n/index.ts or admin-ui/src/i18n/index.ts)
+ *
+ * @example
+ * // Frontend usage
+ * import { localeMessages } from '@/i18n';
+ * <I18nProvider messages={localeMessages}>{children}</I18nProvider>
+ *
+ * @example
+ * // Admin UI usage
+ * import { localeMessages } from '@admin/i18n';
+ * <I18nProvider messages={localeMessages}>{children}</I18nProvider>
+ */
+export function I18nProvider({ children, messages }: I18nProviderProps): JSX.Element;
+interface CloseButtonProps extends Omit<_ButtonProps1, 'onPress'> {
+    onClose: () => void;
+}
+export const CloseButton: ({ onClose, ...props }: CloseButtonProps) => JSX.Element;
+export interface ComboBoxItem {
+    id: Key;
+    label: string;
+    textValue?: string;
+}
+export interface ComboBoxProps {
+    label?: string;
+    description?: string;
+    errorMessage?: string;
+    isRequired?: boolean;
+    isDisabled?: boolean;
+    selectedKey?: Key | null;
+    onSelectionChange?: (key: Key | null) => void;
+    items: ComboBoxItem[];
+    placeholder?: string;
+    'aria-label'?: string;
+    inputValue?: string;
+    onInputChange?: (value: string) => void;
+}
+/**
+ * Generic ComboBox component for searchable single-selection.
+ *
+ * Uses React Aria Components ComboBox for accessible selection with filtering.
+ * Reusable for any data type - countries, users, categories, etc.
+ *
+ * @example
+ * ```tsx
+ * const items = [
+ *   { id: 1, label: 'Apple' },
+ *   { id: 2, label: 'Banana' },
+ *   { id: 3, label: 'Orange' },
+ * ];
+ *
+ * <ComboBox
+ *   label="Fruit"
+ *   items={items}
+ *   selectedKey={selectedId}
+ *   onSelectionChange={setSelectedId}
+ *   placeholder="Select a fruit"
+ * />
+ * ```
+ */
+export function ComboBox({ label, description, errorMessage, isRequired, isDisabled, selectedKey, onSelectionChange, items, placeholder, 'aria-label': ariaLabel, inputValue: controlledInputValue, onInputChange: controlledOnInputChange, }: ComboBoxProps): JSX.Element;
+export interface DisclosureItem {
+    id: string;
+    title: string;
+    content: React.ReactNode;
+    onPress?: () => void;
+}
+interface CustomDisclosureGroupProps extends Omit<DisclosureGroupProps, 'children'> {
+    items: DisclosureItem[];
+    'aria-label'?: string;
+}
+/**
+ * Reusable DisclosureGroup component
+ * Displays collapsible sections with consistent styling
+ *
+ * @example
+ * <DisclosureGroup
+ *   items={[
+ *     {
+ *       id: 'section1',
+ *       title: 'Section 1',
+ *       content: <div>Content goes here</div>
+ *     }
+ *   ]}
+ * />
+ */
+export function DisclosureGroup({ items, ...props }: CustomDisclosureGroupProps): JSX.Element;
+interface FilterOption {
+    value: string;
+    label: string;
+}
+interface FilterTabsProps {
+    value: string;
+    onChange: (value: string) => void;
+    options: FilterOption[];
+    ariaLabel?: string;
+}
+/**
+ * FilterTabs component for status filtering
+ * Uses React Aria ToggleButtonGroup with SelectionIndicator
+ *
+ * @example
+ * <FilterTabs
+ *   value={statusFilter}
+ *   onChange={setStatusFilter}
+ *   options={[
+ *     { value: 'all', label: 'All' },
+ *     { value: 'running', label: 'Running' }
+ *   ]}
+ *   ariaLabel="Filter by status"
+ * />
+ */
+export function FilterTabs({ value, onChange, options, ariaLabel }: FilterTabsProps): JSX.Element;
+interface LabeledValueProps {
+    label: string;
+    error?: string;
+    description?: string;
+    children: React.ReactNode;
+}
+export function LabeledValue({ label, children, error, description, ...props }: LabeledValueProps): JSX.Element;
+interface CustomLinkProps extends Omit<LinkProps, 'className'> {
+    children: ReactNode;
+    isExternal?: boolean;
+    className?: string | ((renderProps: any) => string);
+}
+/**
+ * Link Component
+ *
+ * Wraps React Aria Components Link with S2 styling and proper a11y.
+ * Automatically handles focus states and keyboard navigation.
+ * External links automatically get target="_blank" and rel="noopener noreferrer".
+ *
+ * @example
+ * <Link href="/ferments">Browse Ferments</Link>
+ *
+ * @example
+ * <Link href="https://example.com" isExternal>External Link</Link>
+ *
+ * @example
+ * <Link href="/" className={customStyles}>Custom Styled Link</Link>
+ */
+export function Link({ children, href, isExternal, className, ...props }: CustomLinkProps): JSX.Element;
+interface RadioGroupProps extends Omit<_RadioGroupProps1, 'children'> {
+    label: string;
+    options: Array<{
+        id: string;
+        label: string;
+        value: string;
+    }>;
+    error?: string;
+}
+export function RadioGroup({ label, options, error, ...props }: RadioGroupProps): JSX.Element;
+interface SearchFieldProps {
+    value: string;
+    onChange: (value: string) => void;
+    label: string;
+    placeholder: string;
+    ariaLabel: string;
+}
+/**
+ * Reusable SearchField component using React Aria Components
+ * Styled with S2 design tokens and includes search icon
+ *
+ * @example
+ * <SearchField
+ *   value={searchQuery}
+ *   onChange={setSearchTerm}
+ *   label="Search"
+ *   placeholder="Search ferments..."
+ *   ariaLabel="Search ferments by name or description"
+ * />
+ */
+export function SearchField({ value, onChange, label, placeholder, ariaLabel, }: SearchFieldProps): JSX.Element;
+interface SegmentedControlProps {
+    value: 'map' | 'list';
+}
+/**
+ * SegmentedControl for Map/List view toggle
+ * Uses RAC ToggleButtonGroup for accessible segmented control
+ */
+export function SegmentedControl({ value }: SegmentedControlProps): JSX.Element;
+export interface SelectOption {
+    id: string;
+    label: string;
+    value: string | null;
+    isDisabled?: boolean;
+}
+interface CustomSelectProps extends Omit<SelectProps<SelectOption>, 'children'> {
+    label: string;
+    options: SelectOption[];
+    placeholder?: string;
+}
+/**
+ * Reusable Select component following RAC pattern
+ * Label is inside the Select wrapper for proper a11y
+ */
+export function Select({ label, options, placeholder, ...props }: CustomSelectProps): JSX.Element;
+interface StatCardProps {
+    title: string;
+    value: ReactNode;
+    description?: string;
+}
+/**
+ * StatCard component for displaying dashboard statistics
+ *
+ * @example
+ * <StatCard
+ *   title="Total Sources"
+ *   value={42}
+ *   description="Active scraping sources"
+ * />
+ *
+ * @example
+ * // With icon as value
+ * <StatCard
+ *   title="System Status"
+ *   value={<CheckmarkCircle />}
+ *   description="All systems operational"
+ * />
+ */
+export function StatCard({ title, value, description }: StatCardProps): JSX.Element;
+interface SwitchProps extends Omit<_SwitchProps1, 'children'> {
+    children?: React.ReactNode;
+}
+export const Switch: ({ children, ...props }: SwitchProps) => JSX.Element;
+export function Tabs({ children, ...props }: TabsProps): JSX.Element;
+export function TabList<T extends object>({ children, ...props }: TabListProps<T>): JSX.Element;
+export function Tab({ children, ...props }: TabProps): JSX.Element;
+export function TabPanel({ children, ...props }: TabPanelProps): JSX.Element;
+interface TextAreaProps extends Omit<TextFieldProps, 'type'> {
+}
+export function TextArea({ label, error, placeholder, value, ...props }: TextAreaProps): JSX.Element;
+type ColorScheme = 'light' | 'dark';
+interface ThemeContextType {
+    colorScheme: ColorScheme;
+    toggleColorScheme: () => void;
+}
+export function ThemeProvider({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+export function useTheme(): ThemeContextType;
+/**
+ * Type definitions for FermMap
+ *
+ * Shared types used across the application
+ */
+export interface FilterState {
+    category: string | null;
+    country: string | null;
+    searchQuery: string;
+}
+export interface CategoryColors {
+    marker: string;
+    badge: BadgeVariant;
+}
+/**
+ * Type definitions for FermMap
+ *
+ * Shared types used across the application
+ */
+export interface Ferment {
+    id: number;
+    name: string;
+    slug: string;
+    description: string;
+    country: string;
+    countryCode: string;
+    region: string;
+    regionName?: string | null;
+    category: string;
+    ingredients: string[] | null;
+    imageUrl: string | null;
+    sourceUrl: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    relatedFerments?: RelatedFerment[];
+}
+export interface RelatedFerment {
+    id: number;
+    name: string;
+    slug: string;
+    category?: string;
+    imageUrl?: string | null;
+    country: string;
+    countryCode?: string;
+}
+export interface Country {
+    code: string;
+    name: string;
+    region: string;
+    hasFerments: boolean;
+}
+export interface Category {
+    name: string;
+    category: string;
+}
+/**
+ * Filter context type with state and update methods
+ */
+interface FilterContextType {
+    filters: FilterState;
+    updateFilter: <K extends keyof FilterState>(key: K, value: FilterState[K]) => void;
+    clearFilters: () => void;
+}
+/**
+ * Filter Provider Component
+ * Manages filter state for the application
+ *
+ * @example
+ * <FilterProvider>
+ *   <App />
+ * </FilterProvider>
+ */
+export function FilterProvider({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+/**
+ * Hook to access filter context
+ * Must be used within FilterProvider
+ *
+ * @example
+ * const { filters, updateFilter, clearFilters } = useFilters();
+ * updateFilter('category', 'dairy');
+ */
+export function useFilters(): FilterContextType;
+export function AxeDevTools(): null;
+/**
+ * Default filter state
+ */
+export const DEFAULT_FILTERS: FilterState;
+/**
+ * Check if any filters are active
+ */
+export function hasActiveFilters(filters: FilterState): boolean;
+/**
+ * Clear all filters, returning default state
+ */
+export function clearFilters(): FilterState;
+/**
+ * Update a single filter field
+ */
+export function updateFilter(filters: FilterState, field: keyof FilterState, value: string | null): FilterState;
+/**
+ * Convert filter state to API query parameters
+ * Only includes non-empty filters
+ */
+export function filtersToQueryParams(filters: FilterState): Record<string, string>;
+/**
+ * Get colors for a ferment category
+ * Returns marker color (for map), badge background, and badge text color
+ *
+ * @example
+ * const colors = getCategoryColors('dairy');
+ * // { marker: 'var(--plum-500)', badge: 'plum' }
+ */
+export function getCategoryColors(category: string): CategoryColors;
+export interface FermentsResponse {
+    ferments: Ferment[];
+    count: number;
+    filters?: {
+        category?: string;
+        country?: string;
+    };
+}
+export interface FermentDetailResponse extends Ferment {
+    relatedFerments: Array<RelatedFerment>;
+}
+export interface SearchResponse {
+    results: Ferment[];
+    query: string;
+    count: number;
+}
+export interface FilterOptions {
+    category?: string;
+    country?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * API client object with all endpoint methods
+ */
+export const api: {
+    /**
+     * Get list of ferments with optional filters
+     */
+    getFerments(filters?: FilterOptions): Promise<FermentsResponse>;
+    /**
+     * Get optimized data for map markers
+     */
+    getFermentsForMap(): Promise<{
+        ferments: Array<Pick<Ferment, "id" | "name" | "latitude" | "longitude" | "category" | "country">>;
+    }>;
+    /**
+     * Search ferments by name or description
+     */
+    searchFerments(query: string): Promise<SearchResponse>;
+    /**
+     * Get list of countries with hasFerments flag
+     * Optionally filtered by category
+     */
+    getCountries(category?: string): Promise<{
+        countries: Country[];
+    }>;
+    /**
+     * Get list of categories
+     * Optionally filtered by country
+     */
+    getCategories(country?: string): Promise<{
+        categories: Category[];
+    }>;
+};
+
+//# sourceMappingURL=types.d.ts.map