themelia-react-ui 0.0.0-stage → 1.0.0

package/dist/components/features/filters/partials/async-filter-content.d.ts

@@ -0,0 +1,21 @@
+import type { FilterConfig, FilterTriggerSource } from '../filters.types';
+interface AsyncFilterContentProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Current value. */
+    value: string[];
+    /** Fired when the change filters change. */
+    onFilterChange: (value: string[]) => void;
+    onBackToFilterList: () => void;
+    onClose: () => void;
+    /** Origin of the editor, which determines back-button behavior. */
+    triggerSource?: FilterTriggerSource;
+}
+/**
+ * Async Filter Content – renders inside the popover pipeline.
+ *
+ * Matches the layout of RegularFilterContent (header + command list + footer)
+ * but fetches options asynchronously through the framework-agnostic hook.
+ */
+export declare function AsyncFilterContent({ filter, value, onFilterChange, onBackToFilterList, onClose, triggerSource, }: AsyncFilterContentProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/date-filter-content.d.ts

@@ -0,0 +1,14 @@
+import type { FilterConfig, FilterTriggerSource } from '../filters.types';
+interface DateFilterContentProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Current value. */
+    value: string[];
+    /** Fired when the change filters change. */
+    onFilterChange: (value: string[]) => void;
+    onBackToFilterList: () => void;
+    /** Origin of the editor, which determines back-button behavior. */
+    triggerSource?: FilterTriggerSource;
+}
+export declare function DateFilterContent({ filter, value, onFilterChange, onBackToFilterList, triggerSource, }: DateFilterContentProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/filter-error-boundary.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+export interface FilterErrorBoundaryProps {
+    children: ReactNode;
+    /** Key identifying which filter this content edits. */
+    filterKey?: string;
+    /** Shown when the primary content is unavailable. */
+    fallback?: ReactNode;
+}
+export declare function FilterErrorBoundary(props: FilterErrorBoundaryProps): import("react").JSX.Element;

package/dist/components/features/filters/partials/filter-list-content.d.ts

@@ -0,0 +1,24 @@
+import type { FilterConfig } from '../filters.types';
+interface FilterListContentProps {
+    /** Filters the user may add. */
+    availableFilters: FilterConfig[];
+    /** Filters currently applied. */
+    activeFilters: FilterConfig[];
+    /** Fired when the select filters change. */
+    onFilterSelect: (filter: FilterConfig) => void;
+}
+/**
+ * Filter Popover Content Component
+ *
+ * This component provides the content wrapper for filter popovers.
+ * It handles:
+ * - Consistent popover styling
+ * - Content layout and spacing
+ * - Responsive behavior
+ * - Animation and transitions
+ *
+ * The component is used to wrap filter content in a consistent
+ * popover interface across different filter types.
+ */
+export declare function FilterListContent({ availableFilters, activeFilters, onFilterSelect, }: FilterListContentProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/filter-list-item.d.ts

@@ -0,0 +1,19 @@
+import { type FilterConfig } from '../filters.types';
+interface FilterListItemProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Fired when an entry is activated. */
+    onSelect: () => void;
+}
+/**
+ * FilterListItem — single row inside the Filters-button menu.
+ *
+ * Shows a leading icon (rendered as-is so its native colour comes through),
+ * the filter label as the primary line, and a secondary "{n} options" line
+ * for SELECT-style filters or the "select date range" hint for DATE filters.
+ *
+ * All typography flows through the base Text component so the global
+ * scale + theming applies consistently.
+ */
+export declare function FilterListItem({ filter, onSelect }: FilterListItemProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/filter-operator-select.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { FilterOperator, OperatorOption } from '../filters.types';
+export interface FilterOperatorSelectProps {
+    /** Comparison currently chosen. */
+    operator: FilterOperator;
+    /** Comparisons this filter offers. */
+    operators: OperatorOption[];
+    onOperatorChange: (operator: FilterOperator) => void;
+    /** Segment-reset classes forwarded by the parent pill so the trigger
+     *  drops its base border + focus ring (it lives inside a segmented
+     *  pill, not as a standalone button). */
+    segmentResetClass?: string;
+}
+/**
+ * FilterOperatorSelect — operator dropdown for an active filter pill.
+ *
+ * Now delegates the trigger + popover + command-list pattern entirely to
+ * `PopoverMenu`. The trigger is rendered in the pill's inline strip, the
+ * `header` slot supplies the "Operator" display label, and item rendering
+ * keeps density-tokenized padding while primary labels follow Typography.
+ */
+export declare function FilterOperatorSelect({ operator, operators, onOperatorChange, segmentResetClass, }: FilterOperatorSelectProps): React.JSX.Element;

package/dist/components/features/filters/partials/filter-pill.d.ts

@@ -0,0 +1,26 @@
+import type { FilterConfig, FilterOperator, OperatorOption } from '../filters.types';
+export interface FilterPillProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Current value. */
+    value: string[];
+    /** Whether the filter is currently applied. */
+    active: boolean;
+    /** Comparison currently chosen. */
+    operator: FilterOperator;
+    /** Comparisons this filter offers. */
+    operators: OperatorOption[];
+    onOperatorChange: (operator: FilterOperator) => void;
+    onValueChange: (value: string[]) => void;
+    onClear: () => void;
+    /** Filters to render in the "+" list inside the popover. */
+    availableFilters: FilterConfig[];
+    /** Active regular filters list (for the popover header / context). */
+    activeFilters: FilterConfig[];
+    /** External signal to suppress popover open during operator change. */
+    operatorChangeRef?: React.MutableRefObject<boolean>;
+}
+export declare function FilterPill({ filter, value, active, operator, operators, onOperatorChange, onValueChange, onClear, availableFilters, activeFilters, operatorChangeRef, }: FilterPillProps): import("react").JSX.Element;
+export declare namespace FilterPill {
+    var displayName: string;
+}

package/dist/components/features/filters/partials/filter-popover-content.d.ts

@@ -0,0 +1,36 @@
+import type { ComponentProps } from 'react';
+import { PopoverContent } from '../../../base/popover';
+import { type FilterConfig, type FilterTriggerSource } from '../filters.types';
+export interface FilterPopoverContentProps {
+    /** Which filter the popover is currently editing. */
+    activeFilterInPopover: FilterConfig | null;
+    /** Filters the user may add. */
+    availableFilters: FilterConfig[];
+    /** Filters currently applied. */
+    activeFilters: FilterConfig[];
+    /** Reads the current value of a filter. */
+    getFilterValue: (key: string) => string[];
+    /** Writes the next value of a filter. */
+    setFilterValue: (key: string, value: string[]) => void;
+    /** Fired when the select filters change. */
+    onFilterSelect: (filter: FilterConfig) => void;
+    onBackToFilterList: () => void;
+    onClose: () => void;
+    /** Origin of the editor, which determines back-button behavior. */
+    triggerSource?: FilterTriggerSource;
+    finalFocus?: ComponentProps<typeof PopoverContent>['finalFocus'];
+}
+/**
+ * Filter Popover Content Component
+ *
+ * This component provides the content wrapper for filter popovers.
+ * It handles:
+ * - Consistent popover styling
+ * - Content layout and spacing
+ * - Responsive behavior
+ * - Animation and transitions
+ *
+ * The component is used to wrap filter content in a consistent
+ * popover interface across different filter types.
+ */
+export declare function FilterPopoverContent({ activeFilterInPopover, availableFilters, activeFilters, getFilterValue, setFilterValue, onFilterSelect, onBackToFilterList, onClose, triggerSource, finalFocus, }: FilterPopoverContentProps): import("react").JSX.Element;

package/dist/components/features/filters/partials/filter-tabs.d.ts

@@ -0,0 +1,14 @@
+import { type FilterTab } from '../filters.types';
+export interface FilterTabsProps {
+    /** Tabs to offer, in display order. */
+    tabs: FilterTab[];
+}
+/**
+ * Single-selection filter preset buttons with Base UI roving keyboard navigation.
+ * These change filters rather than switch associated tab panels.
+ *
+ * - "All" tab (empty presets): active when zero non-search active filters
+ * - Named tabs: active when presets exactly match non-search active filters
+ * - Search filters are preserved across tab switches
+ */
+export declare function FilterTabs({ tabs }: FilterTabsProps): import("react").JSX.Element | null;

package/dist/components/features/filters/partials/filter-value-display.d.ts

@@ -0,0 +1,21 @@
+import { type FilterConfig } from '../filters.types';
+export interface FilterValueDisplayProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Current value. */
+    value: string[];
+}
+/**
+ * Filter Value Display Component
+ *
+ * This component provides the UI for displaying filter values.
+ * It handles:
+ * - Displaying filter values with appropriate formatting
+ * - Showing icons for filter options
+ * - Handling date formatting
+ * - Supporting internationalization
+ *
+ * The component is used to show users the current value of a filter
+ * in a consistent and informative way.
+ */
+export declare function FilterValueDisplay({ filter, value }: FilterValueDisplayProps): import("react").JSX.Element;

package/dist/components/features/filters/partials/filters-button.d.ts

@@ -0,0 +1,32 @@
+import { type Ref } from 'react';
+import type { FilterConfig } from '../filters.types';
+export interface FiltersButtonProps {
+    /** Receives the Add filter trigger, for focus restoration in custom layouts. */
+    triggerRef?: Ref<HTMLButtonElement>;
+    /** Filters the user may add. */
+    availableFilters: FilterConfig[];
+    /** Filters currently applied. */
+    activeFilters: FilterConfig[];
+    /** Which filter the popover is currently editing. */
+    activeFilterInPopover: FilterConfig | null;
+    /** Reads the current value of a filter. */
+    getFilterValue: (key: string) => string[];
+    /** Writes the next value of a filter. */
+    setFilterValue: (key: string, value: string[]) => void;
+    /** Opens the popover on a particular filter. */
+    setActiveFilterInPopover: (filter: FilterConfig | null) => void;
+}
+/**
+ * Filters Button Component
+ *
+ * This component provides the main button for adding and managing filters.
+ * It handles:
+ * - Opening the filter popover
+ * - Managing filter selection state
+ * - Handling filter actions (select, back, close)
+ * - Supporting internationalization
+ *
+ * The component is used as the primary entry point for users to
+ * add and configure filters in the application.
+ */
+export declare function FiltersButton({ triggerRef, availableFilters, activeFilters, activeFilterInPopover, getFilterValue, setFilterValue, setActiveFilterInPopover, }: FiltersButtonProps): import("react").JSX.Element;

package/dist/components/features/filters/partials/index.d.ts

@@ -0,0 +1,14 @@
+export * from './active-filter-item';
+export * from './async-filter-content';
+export * from './date-filter-content';
+export * from './filter-error-boundary';
+export * from './filter-list-content';
+export * from './filter-list-item';
+export * from './filter-operator-select';
+export * from './filter-pill';
+export * from './filter-popover-content';
+export * from './filters-button';
+export * from './filter-value-display';
+export * from './regular-filter-content';
+export * from './filter-tabs';
+export * from './search-filters-list';

package/dist/components/features/filters/partials/regular-filter-content.d.ts

@@ -0,0 +1,28 @@
+import { type FilterConfig, type FilterTriggerSource } from '../filters.types';
+interface RegularFilterContentProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Current value. */
+    value: string[];
+    /** Fired when the change filters change. */
+    onFilterChange: (value: string[]) => void;
+    onBackToFilterList: () => void;
+    onClose: () => void;
+    /** Origin of the editor, which determines back-button behavior. */
+    triggerSource?: FilterTriggerSource;
+}
+/**
+ * RegularFilterContent — popover body for SELECT / MULTI_SELECT filters.
+ *
+ * Layout:
+ *   - Compact header: optional back-arrow and shared primary title.
+ *   - Inline search input (only if the filter has more than 5 options).
+ *   - Tight list of options whose primary labels inherit the Typography default.
+ *   - Compact footer: selected count on the leading edge, Confirm button on
+ *     the trailing edge — only rendered when the user has changed selection.
+ *
+ * Sizes are tuned to feel like a native menu, not a card. Popover width
+ * stays at ~260-300px so labels read at one glance.
+ */
+export declare function RegularFilterContent({ filter, value, onFilterChange, onBackToFilterList, onClose, triggerSource, }: RegularFilterContentProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/search-filters-list.d.ts

@@ -0,0 +1,25 @@
+import type { FilterConfig } from '../filters.types';
+export interface SearchFiltersListProps {
+    /** Filter definitions available to the surface. */
+    filters: FilterConfig[];
+    /** Reads the current value of a filter. */
+    getFilterValue: (key: string) => string[];
+    /** Writes the next value of a filter. */
+    setFilterValue: (key: string, value: string[]) => void;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+/**
+ * Search Filters List Component
+ *
+ * This component provides a list of search filters that are always visible.
+ * It handles:
+ * - Rendering multiple search filters
+ * - Managing filter values
+ * - Applying custom styling
+ * - Supporting responsive layout
+ *
+ * The component is used to display search filters that should be
+ * immediately accessible to users without requiring a popover.
+ */
+export declare function SearchFiltersList({ filters, getFilterValue, setFilterValue, className, }: SearchFiltersListProps): import("react").JSX.Element;

package/dist/components/features/filters/partials/tags-filter-content.d.ts

@@ -0,0 +1,28 @@
+import type { FilterConfig, FilterTriggerSource } from '../filters.types';
+interface TagsFilterContentProps {
+    /** Definition of the filter this control edits. */
+    filter: FilterConfig;
+    /** Current value. */
+    value: string[];
+    /** Fired when the change filters change. */
+    onFilterChange: (value: string[]) => void;
+    onBackToFilterList: () => void;
+    onClose: () => void;
+    /** Origin of the editor, which determines back-button behavior. */
+    triggerSource?: FilterTriggerSource;
+}
+/**
+ * Tags Filter Content Component
+ *
+ * This component provides the content for tags filter popovers.
+ * It handles:
+ * - Tag input and management
+ * - Multiple tag selection
+ * - Displaying and removing tags
+ * - Applying filter changes
+ *
+ * The component wraps the TagsFacet component and provides
+ * the popover-specific UI elements like header and action buttons.
+ */
+export declare function TagsFilterContent({ filter, value, onFilterChange, onBackToFilterList, onClose, triggerSource, }: TagsFilterContentProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/utils/filter-utils.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+import type { FilterConfig, FilterDependency } from '../filters.types';
+/**
+ * Gets the label for a filter option
+ */
+export declare function getFilterOptionLabel(filter: FilterConfig, value: string): string | undefined;
+/**
+ * Gets the icon for a filter option
+ */
+export declare function getFilterOptionIcon(filter: FilterConfig, value: string): ReactNode | undefined;
+/**
+ * Validates a filter value against the filter configuration
+ *
+ * @param filter - The filter configuration to validate against
+ * @param value - The value to validate
+ * @param t
+ * @returns true if valid, or an error message string if invalid
+ */
+export declare function validateFilterValue(filter: FilterConfig, value: unknown, t: (key: string) => string): boolean | string;
+/**
+ * Formats a filter value for display using either the format function provided
+ * in the filter config, or by looking up option labels
+ *
+ * @param filter - The filter configuration
+ * @param value - The value to format
+ * @returns Formatted string representation of the value
+ */
+export declare function formatFilterValue(filter: FilterConfig, value: unknown): string;
+/**
+ * Gets the values of dependent filters
+ */
+export declare function getDependentFilterValues(dependencies: FilterDependency[], filterState: Record<string, string[]>): Record<string, string[]>;
+/**
+ * Determines if a filter should be shown based on its dependencies
+ */
+export declare function shouldShowFilter(filter: FilterConfig, filterState: Record<string, string[]>): boolean;
+export declare function extractFilterDefaults<T extends string = string>(filters: FilterConfig[]): Record<T, string>;

package/dist/components/features/filters/validators.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Validator helpers for `FilterConfig.validation.custom`.
+ *
+ * Our `ValidationConfig` accepts `custom: (value) => boolean | string`
+ * already (`true` = valid, `false` = generic invalid, `string` = custom
+ * error message). These helpers adapt common third-party validators
+ * — Zod, Valibot, plain async-safe predicates — to that shape so
+ * consumers don't reinvent the bridge.
+ *
+ * The library does NOT depend on Zod or any specific validation lib.
+ * The helpers are written against minimal duck-typed shapes that any
+ * library implementing `safeParse` can satisfy.
+ */
+import type { ValidationConfig } from './filters.types';
+/**
+ * Minimal Zod-compatible interface — a schema with a `safeParse` method
+ * that returns `{ success: boolean, error?: { message?: string,
+ * issues?: { message: string }[] } }`. Both Zod 3 and Zod 4 satisfy
+ * this; Valibot's `safeParse` differs slightly but a thin wrapper
+ * works.
+ */
+export interface SafeParseSchema<TInput = unknown> {
+    safeParse(value: TInput): {
+        success: boolean;
+        error?: {
+            message?: string;
+            issues?: {
+                message: string;
+            }[];
+        };
+    };
+}
+/**
+ * Adapter: turn a Zod-like schema into a `ValidationConfig['custom']`.
+ *
+ *     import { z } from 'zod';
+ *     import { zodValidator } from '.';
+ *
+ *     const emailSchema = z.string().email();
+ *     const config: FilterConfig = {
+ *         …,
+ *         validation: { custom: zodValidator(emailSchema) },
+ *     };
+ *
+ * On parse failure the first issue's `message` is returned (so
+ * Zod's `.refine(...).message('Custom')` flows through). On success
+ * returns `true`. The empty-string case is bypassed — let
+ * `validation.required` handle "must not be empty" so error messages
+ * stay coherent.
+ */
+export declare function zodValidator<TInput = unknown>(schema: SafeParseSchema<TInput>): NonNullable<ValidationConfig['custom']>;
+/**
+ * Adapter: pair a predicate with a static error message. Useful when
+ * the consumer doesn't want to pull a validation library at all.
+ *
+ *     validation: {
+ *         custom: predicateValidator(
+ *             (v) => /^https?:\/\//.test(String(v)),
+ *             'URL must start with http:// or https://',
+ *         ),
+ *     }
+ */
+export declare function predicateValidator(predicate: (value: unknown) => boolean, message: string): NonNullable<ValidationConfig['custom']>;

package/dist/components/features/global-search/global-search-dialog.d.ts

@@ -0,0 +1,13 @@
+import { type GlobalSearchProps } from './global-search';
+export interface GlobalSearchDialogProps<TGroup extends string = string> extends Omit<GlobalSearchProps<TGroup>, 'onClose'> {
+    /** Whether the palette is showing. */
+    open: boolean;
+    /** Open-state callback. Fires on Escape, backdrop click, and result selection. */
+    onOpenChange: (open: boolean) => void;
+    /** Classes for the dialog surface that positions the palette. */
+    contentClassName?: string;
+}
+export declare function GlobalSearchDialog<TGroup extends string = string>({ open, onOpenChange, contentClassName, className, strings: stringsProp, autoFocus, ...searchProps }: GlobalSearchDialogProps<TGroup>): import("react").JSX.Element;
+export declare namespace GlobalSearchDialog {
+    var displayName: string;
+}

package/dist/components/features/global-search/global-search.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GlobalSearch — framework-agnostic spotlight overlay for app-wide search.
+ *
+ * Composition seams:
+ *   - `strings`        — deep-partial override of the default copy
+ *   - `slots`          — replace any region (input, tabs, idle, empty, loading, footer)
+ *   - `slots.renderResult` — full per-row override
+ *
+ * Headless usage:
+ *   - Call `useGlobalSearch({ results, query })` directly to drive a
+ *     completely custom UI against the same selection state machine.
+ *
+ * Framework-agnostic:
+ *   - No router import, no i18n SDK import. Routing is up to the consumer
+ *     via `onResultSelect`. Strings live in the `strings` prop.
+ *   - The library no longer ships `adapters/$framework/`. Consumers map
+ *     their router (Inertia, Tanstack Router, RR7, Next, …) to
+ *     `onResultSelect(result)` directly at the call site.
+ */
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type GlobalSearchStrings } from './global-search.strings';
+import type { GlobalSearchIdleSection, GlobalSearchResult, GlobalSearchSlots, GlobalSearchTab } from './global-search.types';
+export interface GlobalSearchProps<TGroup extends string = string> {
+    /** Result list. The component renders these grouped by `result.group`. */
+    results?: ReadonlyArray<GlobalSearchResult<TGroup>>;
+    /** Current query value (controlled). */
+    query: string;
+    /** Query change callback. */
+    onQueryChange: (q: string) => void;
+    /** Activation callback — fires on row click or Enter. */
+    onResultSelect?: (result: GlobalSearchResult<TGroup>) => void;
+    /** Escape-key callback. */
+    onClose?: () => void;
+    /** Loading flag — switches the input spinner and renders the loading slot. */
+    loading?: boolean;
+    /** Idle-state sections (Recent / Suggestions / …). */
+    idleSections?: ReadonlyArray<GlobalSearchIdleSection>;
+    /** Override default group labels in the tab strip. */
+    groupLabels?: Partial<Record<TGroup, string>>;
+    /** Auto-focus the input on mount. */
+    autoFocus?: boolean;
+    /** Replace any portion of the default copy. */
+    strings?: StringsProp<GlobalSearchStrings>;
+    /** Replace any portion of the layout. */
+    slots?: GlobalSearchSlots<TGroup>;
+    /** Custom tab list — overrides the auto-generated `All + groups`. */
+    tabs?: ReadonlyArray<GlobalSearchTab<TGroup>>;
+    /** Wrapper className. */
+    className?: string;
+}
+export declare function GlobalSearch<TGroup extends string = string>({ results, query, onQueryChange, onResultSelect, onClose, loading, idleSections, groupLabels, autoFocus, strings: stringsProp, slots, tabs, className, }: GlobalSearchProps<TGroup>): React.JSX.Element;

package/dist/components/features/global-search/global-search.strings.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Strings for `GlobalSearch` and its partials. Consumers override via the
+ * `strings` prop on `<GlobalSearch />`; values are deep-merged over these
+ * defaults so partial overrides are safe.
+ */
+export interface GlobalSearchStrings {
+    /** Placeholder copy for the search input. */
+    /** Names the modal presentation for assistive technology. */
+    dialogTitle: string;
+    placeholder: string;
+    /** aria-label for the clear-search icon button. */
+    clear: string;
+    /** Loading-state copy. */
+    loading: string;
+    /** Empty-state title — uses {{query}} as a placeholder. */
+    emptyTitle: string;
+    /** Empty-state body copy. */
+    emptyHint: string;
+    /** Idle-state heading for "Recent" suggestions. */
+    idleRecent: string;
+    /** Idle-state heading for curated "Suggestions". */
+    idleSuggestions: string;
+    /** Tab label for the "All" tab. */
+    tabAll: string;
+    /** Footer "navigate" hint. */
+    footerNavigate: string;
+    /** Footer "open" hint. */
+    footerOpen: string;
+    /** Footer "close" hint. */
+    footerClose: string;
+    /** Trailing N results count. */
+    resultsCount: string;
+    /** "See all" group action — jumps to that tab. */
+    seeAll: string;
+}
+export declare const defaultGlobalSearchStrings: GlobalSearchStrings;