@abyss-project/commons-front-core 3.0.0 → 3.0.1

package/dist/components/Avatars/ProjectAvatar/ProjectAvatar.component.d.ts

@@ -18,8 +18,11 @@ type Props = {
     cache?: string;
     sx?: SxProps;
     getProjectPictureUrl: (projectId: string) => string;
+    /** Enable project info popup on click */
     showProfile?: boolean;
+    /** Project info to display in popup */
     profileInfo?: ProjectAvatarProfileInfo;
+    /** Callback when avatar is clicked */
     onClick?: () => void;
 };
 declare const ProjectAvatar: FC<Props>;

package/dist/components/Avatars/UserAvatar/UserAvatar.component.d.ts

@@ -14,8 +14,11 @@ type Props = {
     cache?: string;
     sx?: SxProps;
     getProfilePictureUrl: (userId: string) => string;
+    /** Enable profile popup on click */
     showProfile?: boolean;
+    /** Profile info to display in popup */
     profileInfo?: UserAvatarProfileInfo;
+    /** Callback when avatar is clicked (even without popup) */
     onClick?: () => void;
 };
 declare const UserAvatar: FC<Props>;

package/dist/components/Cards/ProjectCard/ProjectCard.component.d.ts

@@ -21,6 +21,7 @@ type Props = {
     followingTooltip?: string;
     formatLanguage?: (language: string) => string;
     formatNumber?: (n: number) => string;
+    /** 'compact' reduces banner height and hides some details */
     variant?: 'default' | 'compact';
 };
 declare const ProjectCard: React.FC<Props>;

package/dist/components/CommandPalette/AbyssCommandPalette.d.ts

@@ -1,3 +1,12 @@
 import { FC } from 'react';
 import { AbyssCommandPaletteProps } from './types';
+/**
+ * Presentational, fully-controlled command palette shell shared by every
+ * Abyss host app. It owns the MUI `Dialog`, the search input, the grouped
+ * result rendering, and the keyboard/mouse selection model — nothing else.
+ *
+ * It NEVER fetches, filters or scores: `groups` must already be
+ * filtered/scored/ordered by the host. See the folder README for the two
+ * supported host modes (client-side filtered vs server-side searched).
+ */
 export declare const AbyssCommandPalette: FC<AbyssCommandPaletteProps>;

package/dist/components/CommandPalette/types.d.ts

@@ -1,22 +1,61 @@
 import { ElementType, ReactNode } from 'react';
 import { DialogProps } from '@mui/material';
 import { SxProps, Theme } from '@mui/material/styles';
+/**
+ * A single selectable row in the palette. The host is fully responsible for
+ * building this shape (icon/avatar node, trailing status chip, etc.) — the
+ * shell only renders what it is given.
+ */
 export interface AbyssCommandPaletteItem {
     id: string;
     title: string;
     subtitle?: string;
+    /** Host-supplied icon or avatar node (e.g. `<UserAvatar />`, an MUI icon). */
     icon?: ReactNode;
+    /** Host-supplied trailing node (e.g. a status `<Chip />`). */
     trailing?: ReactNode;
+    /**
+     * Navigation target for this row. When set AND the palette receives a
+     * `linkComponent`, the row renders as a real anchor, which preserves native
+     * browser affordances (ctrl/cmd-click and middle-click open in a new tab).
+     * A plain click still goes through `onSelect`, so hosts keep full control of
+     * side effects (recents, analytics…). Rows without `href` (imperative
+     * commands such as a theme toggle) render as buttons.
+     */
     href?: string;
 }
+/**
+ * A section of already-filtered, already-ordered items with an
+ * already-translated label. The shell never reorders or drops items from a
+ * group — it only skips rendering a section header for a group with zero
+ * items.
+ */
 export interface AbyssCommandPaletteGroup {
     key: string;
+    /** Already translated by the host. */
     label: string;
     items: AbyssCommandPaletteItem[];
 }
+/**
+ * Visual treatment of the currently-highlighted row.
+ * - `'filled'` (default): a solid tinted background on the selected row.
+ *   This is the original/admin look — unchanged.
+ * - `'accent'`: a left accent bar + accent-coloured label (and, via normal
+ *   CSS color inheritance, any host icon using `color="inherit"`), with only
+ *   a faint background tint. This is the original front look.
+ */
 export type AbyssCommandPaletteHighlightVariant = 'filled' | 'accent';
+/**
+ * How a row was selected. Hosts that render rows as anchors (`href` +
+ * `linkComponent`) MUST check `viaAnchor` before navigating themselves:
+ * when it is `true` the router link already handles the navigation, so
+ * navigating again would push a duplicate history entry — and, on a
+ * ctrl/cmd-click, would hijack the current tab instead of letting the
+ * browser open a new one.
+ */
 export interface AbyssCommandPaletteSelectMeta {
     source: 'click' | 'keyboard';
+    /** The row rendered as an anchor AND the browser/router is handling this navigation. */
     viaAnchor: boolean;
 }
 export interface AbyssCommandPaletteProps {
@@ -24,18 +63,42 @@ export interface AbyssCommandPaletteProps {
     onClose: () => void;
     query: string;
     onQueryChange: (query: string) => void;
+    /** Already filtered/scored/ordered by the host — the shell never filters or scores. */
     groups: AbyssCommandPaletteGroup[];
     onSelect: (item: AbyssCommandPaletteItem, groupKey: string, meta: AbyssCommandPaletteSelectMeta) => void;
+    /** Host is fetching/searching. Drives the subtle loading indicator. */
     isLoading?: boolean;
+    /** Already translated by the host. */
     placeholder: string;
+    /** Already translated by the host. Shown when there are no items to display and not loading. */
     emptyLabel: string;
+    /** Already translated by the host. Shown alongside the loading indicator while there is nothing to display yet. */
     loadingLabel?: string;
+    /** Already translated by the host (e.g. keyboard-shortcut hints). */
     footerHints?: ReactNode;
+    /** Max height of the scrollable results area. Defaults to 420. */
     maxHeight?: number | string;
+    /** Host-supplied node rendered right-aligned inside the input row, next to the search field (e.g. an "ESC" hint badge). Omit for none. */
     inputTrailing?: ReactNode;
+    /** Highlighted-row visual treatment. Defaults to `'filled'` (unchanged existing look). */
     highlightVariant?: AbyssCommandPaletteHighlightVariant;
+    /**
+     * Router link component (e.g. react-router's `Link`) used to render rows that
+     * carry an `href` as real anchors, so ctrl/cmd-click and middle-click open a
+     * new tab. Omit it and every row renders as a button (no anchor semantics).
+     * The component receives the row's `href` as its `to` prop.
+     */
     linkComponent?: ElementType;
+    /** Render the dialog full-screen (hosts typically bind this to a mobile breakpoint). */
     fullScreen?: boolean;
+    /**
+     * Styling escape hatch for the dialog surface. When provided it REPLACES the
+     * shell's default paper styling (vertical offset, radius, overflow), so a
+     * host owns its chrome outright — border, gradient, shadow, offset — without
+     * fighting responsive defaults it did not ask for. The shell keeps owning
+     * behaviour either way.
+     */
     paperSx?: SxProps<Theme>;
+    /** Passthrough to the underlying MUI Dialog slots (e.g. a custom backdrop). */
     slotProps?: DialogProps['slotProps'];
 }

package/dist/components/CommandPalette/useCommandPaletteHotkey.d.ts

@@ -1 +1,10 @@
+/**
+ * Opens the command palette on Cmd+K (macOS) / Ctrl+K (Windows/Linux).
+ * Store-agnostic: the host supplies `onOpen` (e.g. a zustand store action or
+ * local `setState`) so this hook has no opinion on where "open" state lives.
+ * Hand-written listener — no cmdk/kbar dependency.
+ *
+ * @param onOpen Called when the hotkey is pressed.
+ * @param enabled When `false`, the listener is not attached at all. Defaults to `true`.
+ */
 export declare const useCommandPaletteHotkey: (onOpen: () => void, enabled?: boolean) => void;

package/dist/components/CookieConsent/AbyssCookieConsentProvider.d.ts

@@ -6,6 +6,15 @@ export interface AbyssCookieConsentProviderProps {
     consentVersion: string;
     isAuthenticated: boolean;
     domain?: string;
+    /**
+     * NO `privacyLinkHref`. The banner's link is the SAME for every app in the estate by
+     * definition, so it belongs to this component and not to its callers.
+     *
+     * It used to be overridable, and every single caller overrode it with the same relative path,
+     * `/legal/privacy` — resolved against its own domain. Seven of the eight served a 404 behind
+     * their cookie banner. The prop had exactly one observed use, and it was the bug; removing it
+     * is what makes the mistake impossible rather than merely fixed.
+     */
     renderBanner?: (api: UseCookieConsent) => React.ReactNode;
 }
 export declare const AbyssCookieConsentProvider: React.FC<AbyssCookieConsentProviderProps>;

package/dist/components/CookieConsent/privacy-link.constant.d.ts

@@ -1 +1,26 @@
+/**
+ * WHERE THE COOKIE BANNER'S "LEARN MORE" LINK POINTS, FOR THE WHOLE ESTATE.
+ *
+ * ═══ WHY THIS IS A LEAF FILE ═══
+ *
+ * It imports nothing. A URL that every app depends on must be readable — and testable — without
+ * dragging the provider, the consent hook and the whole `@abyss-project/main` SDK behind it.
+ *
+ * ═══ WHAT IT REPLACED ═══
+ *
+ * `https://abyss-project.fr/legal/privacy` — a path the marketing site has never served. Every
+ * app that fell back to it, and the four that passed the same path RELATIVE to their own domain,
+ * offered a 404 behind a cookie banner.
+ *
+ * `/cgu` is where the estate actually states what it does with personal data (the
+ * « Confidentialité » article, mobile section included). The marketing site's middleware adds the
+ * locale itself (`/cgu` → `/fr/cgu`), so there is no language to resolve here.
+ *
+ * ⚠️ There is no standalone privacy policy anywhere in the estate. The banner's link is labelled
+ * « En savoir plus » / "Learn more" and asserts nothing more than that, but a dedicated policy is
+ * the thing to write — and when it exists, this constant is the single place to repoint.
+ *
+ * This is a DEFAULT, not a suggestion: a consuming app has no reason to pass `privacyLinkHref`.
+ * Each one that did pointed at its own domain, which is how four satellites came to serve a 404.
+ */
 export declare const DEFAULT_PRIVACY_HREF = "https://abyss-project.fr/cgu";

package/dist/components/Data/AbyssTable/AbyssTable.component.d.ts

@@ -1,6 +1,6 @@
 import { SxProps } from '@mui/material';
 import { ColumnDef, SortingState } from '@tanstack/react-table';
-import { default as React, ReactNode } from 'react';
+import { ReactNode } from 'react';
 export type AbyssTableFilterDef = {
     columnId: string;
     label: string;
@@ -15,8 +15,16 @@ export type AbyssTableProps<TData extends object> = {
     enablePagination?: boolean;
     defaultPageSize?: number;
     pageSizeOptions?: number[];
+    /**
+     * Server-side (manual) sorting: the table reports the sort instead of applying it.
+     *
+     * Without this, a table in `manualPagination` sorts the rows it holds — one page — against
+     * nothing, which reads as broken. See the README's gotcha section.
+     */
     manualSorting?: boolean;
+    /** Host-controlled sort. Only honoured under `manualSorting`. */
     sorting?: SortingState;
+    /** Called with the next sort when the reader clicks a column header. */
     onSortingChange?: (next: SortingState) => void;
     manualPagination?: boolean;
     pageCount?: number;
@@ -25,9 +33,15 @@ export type AbyssTableProps<TData extends object> = {
     onPageChange?: (page: number) => void;
     onPageSizeChange?: (pageSize: number) => void;
     filters?: AbyssTableFilterDef[];
+    /** Controlled server-side search. When provided, the toolbar search box reports
+     *  debounced changes to the host instead of filtering client-side. */
     onSearchChange?: (value: string) => void;
+    /** Current search text when the host owns the search state. */
     searchValue?: string;
+    /** Placeholder for the search box; falls back to the existing i18n `table.search`. */
     searchPlaceholder?: string;
+    /** Debounce applied before calling `onSearchChange`. Defaults to 400ms (the
+     *  value the admin's local table wrapper used). */
     searchDebounceMs?: number;
     emptyMessage?: string;
     emptyContent?: ReactNode;
@@ -38,5 +52,5 @@ export type AbyssTableProps<TData extends object> = {
     isLoading?: boolean;
     renderAboveTable?: ReactNode;
 };
-declare function AbyssTable<TData extends object>({ data, columns, enableGlobalFilter, enableColumnFilters, enableSorting, manualSorting, sorting: externalSorting, onSortingChange, enablePagination, defaultPageSize, pageSizeOptions, manualPagination, pageCount: externalPageCount, totalItems: externalTotalItems, currentPage: externalCurrentPage, onPageChange, onPageSizeChange, filters, onSearchChange, searchValue, searchPlaceholder, searchDebounceMs, emptyMessage, emptyContent, onRowClick, sx, tableLabel, getRowSx, isLoading, renderAboveTable, }: AbyssTableProps<TData>): React.JSX.Element;
+declare function AbyssTable<TData extends object>({ data, columns, enableGlobalFilter, enableColumnFilters, enableSorting, manualSorting, sorting: externalSorting, onSortingChange, enablePagination, defaultPageSize, pageSizeOptions, manualPagination, pageCount: externalPageCount, totalItems: externalTotalItems, currentPage: externalCurrentPage, onPageChange, onPageSizeChange, filters, onSearchChange, searchValue, searchPlaceholder, searchDebounceMs, emptyMessage, emptyContent, onRowClick, sx, tableLabel, getRowSx, isLoading, renderAboveTable, }: AbyssTableProps<TData>): import("react/jsx-runtime").JSX.Element;
 export default AbyssTable;

package/dist/components/Data/AbyssTable/abyss-table.logic.d.ts

@@ -1,26 +1,98 @@
+/**
+ * Pure, dependency-free helpers backing AbyssTable's pagination and search
+ * behaviour. Kept free of React/MUI so they can be spec'd directly (commons
+ * has no jsdom/testing-library — all logic modules are pure-function specs).
+ */
 export interface ResolvePageIndexParams {
+    /** Whether the table is in server-side (manual) pagination mode. */
     manualPagination: boolean;
+    /** Host-controlled page index (0-based), when the host owns pagination. */
     externalCurrentPage?: number;
+    /** The table's own internal pagination state (0-based). */
     internalPageIndex: number;
 }
+/**
+ * Resolves the page index AbyssTable renders, mirroring the component's
+ * existing precedence exactly:
+ * - manual pagination + a host-provided `currentPage` -> the host value wins.
+ * - manual pagination without a host-provided `currentPage` -> falls back to
+ *   the internal pagination state.
+ * - non-manual (client-side) pagination -> always uses the internal state,
+ *   regardless of `externalCurrentPage`.
+ */
 export declare function resolvePageIndex({ manualPagination, externalCurrentPage, internalPageIndex, }: ResolvePageIndexParams): number;
+/**
+ * Whether the toolbar search box should operate as a controlled, debounced,
+ * server-side search (reporting to the host via `onSearchChange`) instead of
+ * AbyssTable's default client-side global filtering.
+ */
 export declare function shouldUseServerSearch(onSearchChange?: (value: string) => void): boolean;
+/**
+ * Resolves the placeholder text shown in the toolbar search box: an explicit
+ * `searchPlaceholder` prop wins, otherwise the caller's fallback (the
+ * component's existing i18n `table.search` message) is used.
+ */
 export declare function resolveSearchPlaceholder(searchPlaceholder: string | undefined, fallback: string): string;
+/** One column's sort direction, mirroring `@tanstack/react-table`'s `SortingState` entry. */
 export interface SortingEntry {
     id: string;
     desc: boolean;
 }
 export interface ResolveSortingStateParams {
+    /** Whether the host owns the sort and applies it itself (server-side). */
     manualSorting: boolean;
+    /** Host-controlled sort, when the host owns it. */
     externalSorting?: SortingEntry[];
+    /** The table's own internal sorting state. */
     internalSorting: SortingEntry[];
 }
+/**
+ * Resolves the sorting state AbyssTable renders its header affordance from.
+ *
+ * The precedence mirrors `resolvePageIndex`, and for the same reason: a host that owns the sort must
+ * see the arrow it asked for, not one the table decided on its own. A host in manual mode that
+ * passes no `sorting` still gets a working header — it just has nothing to restore on a reload.
+ *
+ * Client-side sorting ignores `externalSorting` entirely, so a host cannot half-control the sort and
+ * end up with a header that disagrees with the rows underneath it.
+ */
 export declare function resolveSortingState({ manualSorting, externalSorting, internalSorting, }: ResolveSortingStateParams): SortingEntry[];
+/**
+ * Whether the table must build a sorted row model of its own.
+ *
+ * Never under `manualSorting`: the rows it holds are one page of a result set the server already
+ * ordered, and re-sorting them locally reorders that page against the rest — the failure the
+ * README's gotcha describes, arrived at from the other direction.
+ */
 export declare function shouldSortRowsLocally(enableSorting: boolean, manualSorting: boolean): boolean;
+/**
+ * Whether a column header offers a sort affordance.
+ *
+ * Client-side, the answer is TanStack's: a column with no accessor has no value to compare, so it
+ * cannot be sorted and `getCanSort()` says so.
+ *
+ * Under `manualSorting` that reasoning does not apply. The server does the ordering; the column only
+ * has to name itself. Display-only columns — a cell built from several fields, a chip, an avatar —
+ * are exactly the ones a host wants sortable server-side, and deferring to `getCanSort()` would make
+ * the whole manual-sorting API silently do nothing on them.
+ */
 export declare function isColumnSortable(params: {
     enableSorting: boolean;
     manualSorting: boolean;
+    /** The column's own `enableSorting`, `undefined` when it does not say. */
     columnEnableSorting: boolean | undefined;
+    /** What TanStack answers for client-side sorting. */
     canSortClientSide: boolean;
 }): boolean;
+/**
+ * The next sort after a click on a column header, under `manualSorting`.
+ *
+ * TanStack's own toggle handler is not usable here: it no-ops on a column it considers unsortable,
+ * which under manual sorting is every display-only column — the ones a host most wants ordered by
+ * the server.
+ *
+ * The cycle is ascending, then descending, then nothing. Three states rather than two because
+ * "nothing" is a real answer: it is how a reader goes back to the list's own default order, and a
+ * two-state toggle would trap them between two orders they may not want either of.
+ */
 export declare function nextManualSorting(current: SortingEntry[], columnId: string): SortingEntry[];

package/dist/components/Inputs/AbyssNumberField/AbyssNumberField.component.d.ts

@@ -1,16 +1,34 @@
 import { TextFieldProps } from '@mui/material';
 import { FC } from 'react';
 export type AbyssNumberFieldProps = Omit<TextFieldProps, 'value' | 'onChange'> & {
+    /** The numeric value */
     value: number | null;
+    /** Called with the raw number on change */
     onChange: (value: number | null) => void;
+    /** Format mode */
     mode?: 'number' | 'currency';
+    /** Currency symbol (default: '€') */
     currencySymbol?: string;
+    /** Currency position */
     currencyPosition?: 'start' | 'end';
+    /**
+     * BCP-47 locale for formatting. Defaults to the active IntlProvider locale,
+     * so the decimal separator follows the app language (fr -> "50,00", en ->
+     * "50.00"). Only override to force a specific locale.
+     */
     locale?: string;
+    /** Decimal places (default: 0 for number, 2 for currency) */
     decimals?: number;
+    /**
+     * Thousands separator. Defaults to the active locale's grouping separator;
+     * pass to override.
+     */
     thousandSeparator?: string;
+    /** Min value */
     min?: number;
+    /** Max value */
     max?: number;
+    /** Allow negative */
     allowNegative?: boolean;
 };
 declare const AbyssNumberField: FC<AbyssNumberFieldProps>;

package/dist/components/Inputs/AbyssNumberField/format.d.ts

@@ -1,7 +1,35 @@
+/**
+ * Locale-aware number formatting/parsing helpers for {@link AbyssNumberField}.
+ *
+ * The decimal and grouping separators are derived from the ACTIVE locale
+ * (fr-FR -> "," decimal, en-* -> "." decimal) and are never hardcoded, so a
+ * currency value like 50 renders as "50,00 €" in French and "50.00" in English.
+ * Parsing is intentionally forgiving: a user typing "50,00" or "50" both
+ * round-trip to the numeric 50 that flows back out through onChange.
+ */
 export interface LocaleSeparators {
+    /** Thousands / grouping separator (fr-FR: narrow no-break space, en-US: ","). */
     group: string;
+    /** Decimal separator (fr-FR: ",", en-US: "."). */
     decimal: string;
 }
+/**
+ * Resolve the grouping and decimal separators used by the given BCP-47 locale
+ * by inspecting `Intl.NumberFormat` output. Falls back to space/dot if the
+ * locale is unknown or Intl throws.
+ */
 export declare function getLocaleSeparators(locale: string): LocaleSeparators;
+/**
+ * Format a numeric value for display using the provided locale separators.
+ * Returns an empty string for null/undefined/NaN.
+ */
 export declare function formatNumberValue(value: number | null | undefined, decimals: number, separators: LocaleSeparators): string;
+/**
+ * Parse a user-typed string back into a number.
+ *
+ * Grouping separators (the locale's own group char plus common whitespace
+ * variants) are stripped first, then either "," or "." is accepted as the
+ * decimal marker so that fr comma-input and en dot-input both yield the same
+ * numeric value. Returns null for empty / non-numeric input.
+ */
 export declare function parseNumberInput(raw: string | null | undefined, separators: LocaleSeparators): number | null;

package/dist/components/Inputs/CloudImport/CloudImport.component.d.ts

@@ -23,6 +23,7 @@ type Props = {
     fetchCloudRepository: (cloudId: string) => Promise<IGetRepositoryCloudData>;
     onActivateService: () => Promise<void>;
     onCreateCloud: (name: string) => Promise<void>;
+    /** Host-supplied resolver: avatar + label for any space. */
     getSpaceDisplay?: (space: ISpace) => CloudImportSpaceDisplay;
 };
 declare const CloudImport: React.FC<Props>;

package/dist/components/Inputs/ColorPalette/ColorPalette.component.d.ts

@@ -14,6 +14,8 @@ type Props = {
     size?: ColorPaletteSize | number;
     shape?: ColorPaletteShape;
     showCustomPicker?: boolean;
+    /** Tooltip for the custom-color button. Pass an i18n string from the host
+     *  (defaults to French for legacy callers). */
     customTooltip?: string;
     sx?: SxProps;
 };

package/dist/components/Inputs/ContextSelector/ContextSelector.component.d.ts

@@ -1,23 +1,35 @@
 import { default as React } from 'react';
+/** A project that belongs to an organization. */
 export type ContextSelectorProject = {
     id: string;
     name: string;
+    /** Optional custom avatar (e.g. a `ProjectAvatar`). Falls back to an icon. */
     avatar?: React.ReactNode;
 };
+/** An organization the user belongs to, with its projects. */
 export type ContextSelectorOrganization = {
     id: string;
     name: string;
+    /** Optional custom avatar (e.g. an `OrganizationAvatar`). Falls back to an icon. */
     avatar?: React.ReactNode;
     projects?: ContextSelectorProject[];
 };
+/** The personal ("Mon Espace") scope entry. */
 export type ContextSelectorPersonal = {
+    /** Display label (e.g. the user's alias). Falls back to the i18n "Mon Espace". */
     label?: string;
+    /** Optional custom avatar (e.g. a `UserAvatar`). Falls back to an icon. */
     avatar?: React.ReactNode;
 };
+/** Full data shape: the personal scope plus the user's organizations. */
 export type ContextSelectorData = {
     personal: ContextSelectorPersonal;
     organizations: ContextSelectorOrganization[];
 };
+/**
+ * The currently-selected context. A discriminated union mirroring the
+ * personal / organization / project scope used across the apps.
+ */
 export type ContextValue = {
     kind: 'personal';
 } | {
@@ -28,15 +40,28 @@ export type ContextValue = {
     organizationId: string;
     projectId: string;
 };
+/**
+ * - `grouped`: three flat headers — "Mon Espace", "Organisation", "Projets".
+ * - `by-org`: "Mon Espace" first, then one group per organization (by name),
+ *   each containing an "Organisation" entry + that org's projects.
+ */
 export type ContextSelectorVariant = 'grouped' | 'by-org';
 type ContextSelectorProps = {
+    /** Personal + organizations (each with their projects). */
     data: ContextSelectorData;
+    /** The currently-selected context. */
     value: ContextValue;
+    /** Fires with the new context when the user picks an option. */
     onChange: (next: ContextValue) => void;
+    /** Layout of the option list. Defaults to `grouped`. */
     variant?: ContextSelectorVariant;
+    /** Optional field label rendered by the inner `TextField`. */
     label?: string;
+    /** Optional placeholder for the inner `TextField`. */
     placeholder?: string;
+    /** Disables the whole control. */
     disabled?: boolean;
+    /** Min width of the control. Defaults to 240px. */
     minWidth?: number | string;
 };
 export declare const ContextSelector: React.FC<ContextSelectorProps>;

package/dist/components/Inputs/DatePeriodPicker/DatePeriodPicker.component.d.ts

@@ -4,23 +4,55 @@ import { DatePeriodGranularity } from './date-period-picker.logic';
 import { DatePeriodPreset } from './date-period-presets.util';
 export type { DatePeriodGranularity } from './date-period-picker.logic';
 export type { DatePeriodPreset } from './date-period-presets.util';
+/**
+ * Layout variant. `segmented` renders a single segmented control with a sliding
+ * thumb; the other values render the layouts they name. All six are supported —
+ * pick the one that fits the surface.
+ */
 export type DatePeriodVariant = 'default' | 'compact' | 'inline' | 'presets-only' | 'presets-bar' | 'segmented';
 export type DatePeriodPickerProps = {
     startDate: Date | null;
     endDate: Date | null;
     onStartDateChange: (date: Date | null) => void;
     onEndDateChange: (date: Date | null) => void;
+    /** Called when both dates change at once (e.g. preset click). Avoids stale-closure issues. */
     onRangeChange?: (start: Date | null, end: Date | null) => void;
+    /** Layout variant. @default 'default' */
     variant?: DatePeriodVariant;
+    /**
+     * Time granularity of the resolved range.
+     * - `'day'` (default): presets and custom ranges snap to `startOfDay` /
+     *   `endOfDay` (day-only picker, fully backward-compatible).
+     * - `'minute'`: the custom-range popover exposes hour/minute fields and the
+     *   resolved range keeps the exact selected date + time (no start/end-of-day
+     *   snapping). When a calendar day is picked the currently entered time is
+     *   kept (defaulting to 00:00 for start / 23:59 for end).
+     *
+     * @default 'day'
+     */
     granularity?: DatePeriodGranularity;
+    /** Custom presets. If not provided, defaults are used */
     presets?: DatePeriodPreset[];
+    /** Hide preset chips */
     hidePresets?: boolean;
+    /** Min selectable date */
     minDate?: Date;
+    /** Max selectable date */
     maxDate?: Date;
+    /** Override labels (defaults to translations) */
     startLabel?: string;
     endLabel?: string;
+    /** Hide the date range summary text below the picker */
     hideSummary?: boolean;
+    /** Override label for the Custom date button (presets-bar + segmented variants) */
     customLabel?: string;
+    /**
+     * Explicit date-fns locale used for every `format(...)` call and the picker
+     * calendar. The commons bundle ships its own date-fns copy, so the host's
+     * global `setDefaultOptions({ locale })` never reaches it — the locale must be
+     * passed explicitly. When omitted, the locale is resolved from the active
+     * react-intl language (`intl.locale`), defaulting to English.
+     */
     locale?: Locale;
 };
 declare const DatePeriodPicker: React.FC<DatePeriodPickerProps>;

package/dist/components/Inputs/DatePeriodPicker/date-period-picker.logic.d.ts

@@ -1,25 +1,79 @@
 import { Locale } from 'date-fns';
 export type EditingBound = 'start' | 'end';
+/**
+ * Time granularity of the resolved range.
+ *
+ * - `day` (default): bounds snap to start-of-day (start) / end-of-day (end). The
+ *   picker behaves as a day-only range picker — fully backward-compatible.
+ * - `minute`: bounds keep an explicit hour/minute and resolve to the exact
+ *   selected instant (no start/end-of-day snapping).
+ */
 export type DatePeriodGranularity = 'day' | 'minute';
 export type RangeUpdateInput = {
+    /** Which bound the user is currently editing. */
     editing: EditingBound;
+    /** The day the user just picked in the calendar. */
     picked: Date;
+    /** Current start bound (may be null/invalid). */
     startDate: Date | null;
+    /** Current end bound (may be null/invalid). */
     endDate: Date | null;
+    /**
+     * Time granularity. Defaults to `day` (snap to start/end of day). In `minute`
+     * mode the previously entered time is preserved when only the calendar day
+     * changes.
+     */
     granularity?: DatePeriodGranularity;
 };
 export type RangeUpdateResult = {
+    /** New start bound, or the previous reference when unchanged. */
     start: Date | null;
+    /** New end bound, or the previous reference when unchanged. */
     end: Date | null;
+    /** Whether the start reference changed. */
     startChanged: boolean;
+    /** Whether the end reference changed. */
     endChanged: boolean;
 };
 export type TimeChangeInput = {
+    /** Which bound the user is currently editing. */
     editing: EditingBound;
+    /** The value emitted by the time field (carries the new hour/minute). */
     time: Date;
+    /** Current start bound (may be null/invalid). */
     startDate: Date | null;
+    /** Current end bound (may be null/invalid). */
     endDate: Date | null;
 };
+/**
+ * Pure, independent range-bound update for a calendar day pick.
+ *
+ * Each bound is edited independently: editing the END never moves the START and
+ * vice-versa (fixes the "changing end also moves start" regression). The only
+ * coupling is a validation clamp guaranteeing `end >= start`:
+ * - editing `start` past `end` clamps the start down to `end` (end untouched);
+ * - editing `end` before `start` clamps the end up to `start` (start untouched).
+ *
+ * In `day` granularity (default) bounds are normalized to start-of-day (start) /
+ * end-of-day (end). In `minute` granularity the previously entered time is kept
+ * and only the calendar day changes; the range resolves to the exact instant.
+ */
 export declare const computeRangeUpdate: (input: RangeUpdateInput) => RangeUpdateResult;
+/**
+ * Pure time-of-day update (minute granularity only).
+ *
+ * Applies the hour/minute emitted by a time field to the edited bound while
+ * keeping that bound's calendar day. When the edited bound has no value yet, the
+ * time field's own day is used as the base. The same `end >= start` clamp as
+ * {@link computeRangeUpdate} keeps the range valid without moving the other bound.
+ */
 export declare const applyTimeChange: (input: TimeChangeInput) => RangeUpdateResult;
+/**
+ * Resolve a date-fns `Locale` from an app language code (e.g. the react-intl
+ * `intl.locale`). Defaults to English for unknown / missing codes.
+ *
+ * The specific locales are imported directly so they survive tree-shaking inside
+ * the commons bundle — the host's global `setDefaultOptions` never reaches the
+ * bundle's own date-fns copy, so locale must always be passed explicitly.
+ */
 export declare const resolveDateFnsLocale: (language?: string | null) => Locale;