rich-react-component 0.3.1 → 0.4.0

package/dist/base/chart/chartColors.d.ts

@@ -0,0 +1,4 @@
+import { ChartSeries } from './chartTypes';
+export declare function resolveChartColor(index: number, explicit: string | undefined, overrides: string[] | undefined): string;
+/** Resolves a color for every series in order — the shape `ChartLegend` and every concrete chart need. */
+export declare function chartSeriesColorList(series: readonly ChartSeries[], overrides: string[] | undefined): string[];

package/dist/base/chart/chartScales.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal scale/tick math, written in-house rather than adding a dependency
+ * (d3-scale et al.) — the same call this repo already made for `Sparkline`.
+ * A handful of pure functions is enough for a band + linear axis and stays
+ * inside the library's zero-runtime-dependency footprint for the Base layer.
+ */
+export declare function linearScale(domain: [number, number], range: [number, number]): (value: number) => number;
+/** "Nice" round tick values spanning at least [min, max] — the standard d3-style rounding step. */
+export declare function niceTicks(min: number, max: number, count?: number): number[];
+/** Evenly divides `size` into `count` bands, returning each band's start offset and width. */
+export declare function bandScale(count: number, size: number, paddingRatio?: number): {
+    bandWidth: number;
+    offset: (index: number) => number;
+};
+export declare function defaultNumberFormatter(locale?: string): (value: number) => string;

package/dist/base/chart/chartTypes.d.ts

@@ -0,0 +1,58 @@
+import { ReactNode } from 'react';
+/**
+ * Small, semantic contracts shared by every chart in the family (doc section
+ * 13 — compose small parts rather than one "MassiveChartProps"). Every
+ * concrete chart (LineChart, BarChart, DonutChart, ...) extends the subset
+ * that applies to it.
+ */
+export type ChartValue = string | number | Date;
+export type ChartTone = "primary" | "success" | "warning" | "danger" | "info" | "secondary";
+/** A row of chart data. Cartesian charts index it by `xKey` + each series' `key`; circular charts by `nameKey`/`valueKey`. */
+export type ChartDatum = Record<string, ChartValue | null | undefined>;
+export interface ChartSeries {
+    key: string;
+    label: string;
+    /** Explicit color — a CSS color or a `var(--rrc-*)` reference. Omitted: the chart's palette token assigns one by index. */
+    color?: string;
+    /** Series sharing a `stackId` stack on top of each other in BarChart/StackedBarChart. */
+    stackId?: string;
+    /** Initial visibility; the legend can still toggle it (uncontrolled unless `hiddenSeriesKeys` is passed). */
+    hidden?: boolean;
+    valueFormatter?: (value: number) => string;
+}
+export interface ChartInteraction {
+    seriesKey: string;
+    datum: ChartDatum;
+    value: number;
+    index: number;
+}
+export interface ChartSliceInteraction {
+    key: string;
+    label: string;
+    value: number;
+    index: number;
+    datum: ChartDatum;
+}
+/** Shared status/infrastructure props every chart composes via `Chart`/`ChartStatus` (doc: don't reimplement per chart type). */
+export interface ChartStatusProps {
+    loading?: boolean;
+    /** Non-empty renders the error state instead of the chart. */
+    error?: ReactNode;
+    /** Shown when `data` (or every series in it) is empty. */
+    emptyMessage?: ReactNode;
+    disabled?: boolean;
+}
+export interface ChartCommonProps extends ChartStatusProps {
+    title?: string;
+    /** Fixed height; width is measured from the container (ResizeObserver, SSR-safe fallback). */
+    height?: number;
+    className?: string;
+    showLegend?: boolean;
+    showTooltip?: boolean;
+    /** Disables the CSS entrance animation; also forced off under `prefers-reduced-motion`. */
+    animate?: boolean;
+    /** Accessible name for the chart region; falls back to `title`. */
+    "aria-label"?: string;
+    /** Palette override, applied to series/slices in order before any per-item `color`. */
+    colors?: string[];
+}

package/dist/base/chart/useChartDimensions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Measures the chart's own container width (doc: responsive width, no global
+ * breakpoint). Reuses `useElementResize` (ResizeObserver with a window-resize
+ * fallback, already SSR-safe) instead of a second measurement strategy.
+ *
+ * Starts at 0 so the very first server/client render emits no SVG at all
+ * (avoids a divide-by-zero layout before the real width is known); the
+ * measured width lands on the next paint, which is invisible to the user.
+ */
+export declare function useChartDimensions(): {
+    containerRef: React.RefObject<HTMLDivElement>;
+    width: number;
+};

package/dist/base/chart/useChartIndexNavigation.d.ts

@@ -0,0 +1,23 @@
+import { KeyboardEvent } from 'react';
+export interface UseChartIndexNavigationOptions {
+    count: number;
+    disabled?: boolean;
+    onActivate?: (index: number) => void;
+    onSelect?: (index: number) => void;
+}
+export interface ChartIndexNavigation {
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    clearActive: () => void;
+    handleKeyDown: (event: KeyboardEvent) => void;
+}
+/**
+ * Roving index navigation shared by every chart shape: Left/Right (or the
+ * next/previous data point) moves the focused/hover point, Home/End jump to
+ * the ends, Enter/Space fires the same callback a mouse click on that point
+ * would (doc: "veri noktasına tıklama" and "klavye ile veri noktaları arasında
+ * hareket" are one interaction model, not two). Used for x-categories in the
+ * cartesian charts (Line/Area/Bar/StackedBar) and for slices in the circular
+ * ones (Donut/Pie) — the math is identical, only what "index" means differs.
+ */
+export declare function useChartIndexNavigation({ count, disabled, onActivate, onSelect }: UseChartIndexNavigationOptions): ChartIndexNavigation;

package/dist/base/contextMenuModel.d.ts

@@ -0,0 +1,49 @@
+import { ReactElement, ReactNode } from 'react';
+/**
+ * Identification of the declarative context-menu nodes.
+ *
+ * Recognition is by component *identity*, recorded in a module-private
+ * WeakMap that is written once while this module initializes and never
+ * mutated afterwards. Deliberately not `displayName`, not `Component.name`
+ * and not a string on `props`: those are all rewritten or dropped by a
+ * minifier, which would make the whole feature fail only in a production
+ * bundle. A WeakMap keyed on the component reference survives minification
+ * for exactly the same reason `type === Component` does, and needs no type
+ * assertion to read back.
+ */
+export type ContextMenuNodeKind = "menu" | "item" | "label" | "separator" | "submenu";
+/** Records what a component is. Called once per component at module scope. */
+export declare function markContextMenuNode<TComponent extends object>(component: TComponent, kind: ContextMenuNodeKind): TComponent;
+/** The kind of a rendered node, or `undefined` for anything this module did not mark. */
+export declare function contextMenuNodeKind(node: ReactNode): ContextMenuNodeKind | undefined;
+/**
+ * Flattens the direct children of a node one fragment level at a time.
+ *
+ * Fragments are handled deliberately rather than by accident: a
+ * `<>{menu}{content}</>` child must not hide the menu declaration from the
+ * partition below, and its visible children must not be dropped either.
+ */
+export declare function flattenMenuChildren(children: ReactNode): ReactNode[];
+export interface RichComponentBaseChildren {
+    /** The single `<ContextMenu>` declaration, if one was supplied. */
+    menu?: ReactElement;
+    /** Everything else, rendered as ordinary page content. */
+    content: ReactNode[];
+}
+/**
+ * Splits `RichComponentBase`'s children into the menu declaration and the
+ * visible content. A second `<ContextMenu>` is ignored rather than rendered,
+ * so a stray declaration can never leak into the page as content.
+ */
+export declare function partitionRichComponentBaseChildren(children: ReactNode): RichComponentBaseChildren;
+/**
+ * Whether a declaration would put at least one selectable row on screen.
+ *
+ * This is what decides if the browser's own context menu is suppressed, so it
+ * is answered from the declaration *before* anything is rendered. Labels and
+ * separators do not count — a surface made only of those is "effectively
+ * empty" and must leave native behavior alone. Anything this module did not
+ * mark (a consumer's own wrapper component, arbitrary markup) counts as
+ * content: guessing it away would silently disable a menu that does render.
+ */
+export declare function contextMenuHasContent(children: ReactNode): boolean;

package/dist/base/contextMenuPosition.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure viewport placement math for the context menu surface.
+ *
+ * Kept free of React and of the DOM (the caller measures and passes plain
+ * numbers) so the flip/clamp rules are unit-testable on their own, the same
+ * split `sidebarModel.ts` uses for the Sidebar's navigation model.
+ */
+export interface ContextMenuPoint {
+    x: number;
+    y: number;
+}
+export interface ContextMenuSize {
+    width: number;
+    height: number;
+}
+export interface ContextMenuViewport {
+    width: number;
+    height: number;
+}
+/** Rect of a submenu's trigger row, in viewport coordinates. */
+export interface ContextMenuTriggerBox {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+/** Breathing room kept between the surface and the viewport edge. */
+export declare const CONTEXT_MENU_VIEWPORT_MARGIN = 8;
+/**
+ * Places the root surface at the pointer. Flips to the opposite side of the
+ * pointer when the preferred side would overflow, then clamps, so a menu that
+ * is simply larger than the viewport still starts inside it rather than
+ * scrolling the page.
+ */
+export declare function placeContextMenuAtPoint(point: ContextMenuPoint, size: ContextMenuSize, viewport: ContextMenuViewport, margin?: number): ContextMenuPoint;
+/**
+ * Places a submenu beside its trigger row: flush to the trigger's right edge
+ * by default so the pointer can travel into it without crossing a gap, and
+ * mirrored to the left when that would overflow.
+ */
+export declare function placeSubMenuBeside(trigger: ContextMenuTriggerBox, size: ContextMenuSize, viewport: ContextMenuViewport, margin?: number): ContextMenuPoint;

package/dist/base/dataGridResponsive.d.ts

@@ -0,0 +1,169 @@
+import { RefObject } from 'react';
+/**
+ * Responsive column model for grid-like components.
+ *
+ * The problem: when a grid's *actual available width* is too small for its
+ * visible columns, rows stop being readable. The answer here is an ordered
+ * list of rules that progressively take columns out of the tabular layout —
+ * either relocating them into the row's own label/value detail area
+ * (`"Responsive"`) or dropping them entirely (`"Hide"`) — while one primary
+ * column always stays in the normal row.
+ *
+ * This module owns the whole algorithm: column classification, primary-column
+ * resolution, rule normalization, development-time validation and the
+ * width-driven fit loop. `DataGrid` is its only consumer, and `RemoteDataGrid`
+ * and the Smart `dataGridResolver` inherit the behavior by composing
+ * `DataGrid` — the algorithm exists exactly once.
+ *
+ * It is deliberately React-only-at-the-edges: everything above
+ * `useResponsiveColumnFit` is a pure function of a structural column model,
+ * so it is unit-testable without rendering a grid, and it never imports the
+ * grid itself (no cycle, and the grid stays the sole owner of its column type).
+ */
+/**
+ * What happens to a column when the grid runs out of room for it.
+ *
+ * - `"Responsive"` — leaves the tabular row and is shown as a label/value pair
+ *   in that same row's detail area.
+ * - `"Hide"` — leaves the tabular row and is not shown anywhere.
+ *
+ * Capitalized, unlike this library's other string unions (`"asc"`, `"text"`,
+ * `"auto"`, …), because these two are a specified external contract. One
+ * representation only: the lower-case spellings are deliberately *not*
+ * accepted, so there is never a second competing form of the same concept.
+ */
+export type ResponsiveColumnBehavior = "Responsive" | "Hide";
+/**
+ * One entry of the ordered rule list. Position in the array is the priority —
+ * there is no separate priority number to keep in sync with it.
+ */
+export interface ResponsiveColumnRule<TField> {
+    field: TField;
+    behavior: ResponsiveColumnBehavior;
+}
+export interface GridResponsiveOptions<TField> {
+    /**
+     * The column that carries the row's identity in a narrow layout. It always
+     * stays in the tabular row: it is never relocated to the detail area and
+     * never removed by a `"Hide"` rule.
+     */
+    primaryColumn?: TField;
+    /**
+     * Ordered rules. The first is processed first as width shrinks, and the last
+     * processed is the first restored as width grows. Columns not listed here
+     * are still handled — see `buildResponsiveColumnPlan`.
+     */
+    columns?: readonly ResponsiveColumnRule<TField>[];
+}
+/**
+ * The parts of a grid column this model needs, as a structural shape.
+ *
+ * `isData` / `isUtility` / `isTextual` are classifications the grid derives
+ * from its own column type, so this module never has to know what a
+ * `DataGridColumn` is.
+ */
+export interface ResponsiveColumnModel {
+    /** The grid's own column identity. */
+    key: string;
+    /** Reads a value out of the row (as opposed to a command/action column). */
+    isData: boolean;
+    /** A command/action/control column: renders arbitrary content, reads no value. */
+    isUtility: boolean;
+    /** A data column whose value is textual, so it reads well as a row title. */
+    isTextual: boolean;
+}
+export type ResponsiveProblemKind = "unknown-column" | "duplicate-rule" | "primary-column-rule" | "invalid-behavior" | "utility-column-responsive" | "invalid-primary-column";
+/** One development-time diagnostic, in the same shape the demo registry uses. */
+export interface ResponsiveProblem {
+    kind: ResponsiveProblemKind;
+    detail: string;
+}
+/** A rule after validation, addressed by the grid's resolved column key. */
+export interface NormalizedResponsiveRule {
+    key: string;
+    behavior: ResponsiveColumnBehavior;
+}
+export interface ResponsiveColumnPlan {
+    /** Resolved primary column, or `undefined` when no column is eligible. */
+    primaryKey: string | undefined;
+    /** The single ordered list the fit loop walks. */
+    rules: readonly NormalizedResponsiveRule[];
+    problems: readonly ResponsiveProblem[];
+}
+/**
+ * Deterministic resolution, in order:
+ *
+ * 1. the configured `primaryColumn`, when it names an eligible column;
+ * 2. otherwise the first textual data column in declared column order;
+ * 3. otherwise the first data column in declared column order;
+ * 4. otherwise `undefined` — the grid keeps its existing behavior.
+ *
+ * Utility columns (selection, row number, expanders, actions, command and
+ * drag-handle columns) are never chosen automatically, and a configured one is
+ * rejected: a checkbox or a button is not a row's identity.
+ *
+ * A configured column that is absent from the current column set — because it
+ * was filtered out upstream by a column chooser, by a permission check or by
+ * Smart metadata — cannot be the *visible* primary column, so resolution falls
+ * through to the automatic rules. Nothing about the upstream decision is
+ * touched or written back.
+ */
+export declare function resolvePrimaryColumnKey(columns: readonly ResponsiveColumnModel[], configured: string | undefined): string | undefined;
+/**
+ * Turns the configured options into one ordered, validated rule list.
+ *
+ * Configured rules come first, in their declared order. Every remaining
+ * eligible data column is then appended in *declared column order* with the
+ * default `"Responsive"` behavior, so responsive layout works without asking
+ * a consumer to describe every column — and nothing is hidden by default.
+ *
+ * Skipped, each with a diagnostic: a rule for an unknown column, a duplicate
+ * rule, a rule for the primary column, a rule with an invalid behavior, and a
+ * `"Responsive"` rule for a utility column (an action cell has no meaningful
+ * label/value form). A `"Hide"` rule for a utility column is honored — that is
+ * an explicit instruction to drop a control when space runs out, not a silent
+ * loss of data. Utility columns are never added by default.
+ */
+export declare function buildResponsiveColumnPlan(columns: readonly ResponsiveColumnModel[], options: GridResponsiveOptions<string> | undefined): ResponsiveColumnPlan;
+/**
+ * A stable string identity for one plan. Used to reset the fit loop and to
+ * report diagnostics once per configuration rather than once per render or —
+ * far worse — once per resize.
+ */
+export declare function responsivePlanSignature(plan: ResponsiveColumnPlan): string;
+export interface ResponsiveColumnFitOptions {
+    enabled: boolean;
+    /** The grid's own scroll container — the element whose width actually matters. */
+    containerRef: RefObject<HTMLElement | null>;
+    ruleCount: number;
+    /** Resets the loop when the columns or the rules themselves change. */
+    signature: string;
+}
+/**
+ * How many rules are currently applied.
+ *
+ * Overflow is read from the grid's existing scroll container
+ * (`scrollWidth` vs `clientWidth`) rather than from a re-implementation of
+ * column sizing, so the browser's own table layout — fixed, minimum and
+ * maximum column widths, measured content, `white-space` — remains the single
+ * sizing authority. Two DOM reads per pass, independent of row count: the
+ * algorithm is O(1) in rows and never scans cells.
+ *
+ * Shrinking applies one more rule per pass and records the width at which the
+ * previous count did not fit. Growing releases one rule per pass, but only
+ * once the container is wider than that recorded width plus the hysteresis, so
+ * a restore that would immediately overflow again is not attempted. Passes are
+ * capped per width, so a pathological layout cannot loop forever.
+ */
+export declare function useResponsiveColumnFit({ enabled, containerRef, ruleCount, signature, }: ResponsiveColumnFitOptions): number;
+/**
+ * Reports configuration problems once per configuration.
+ *
+ * Follows the library's existing development-time validation convention
+ * (`useControllableState`, `Sidebar`): `NODE_ENV`-guarded, `console.error`
+ * with the `[react-components]` prefix, from an effect keyed on a stable
+ * signature — so it never throws during render and never logs on resize.
+ * Production fails safe: the malformed rule is skipped, and no data is hidden
+ * because of it.
+ */
+export declare function useResponsivePlanDiagnostics(plan: ResponsiveColumnPlan, signature: string): void;

package/dist/base/index.d.ts

@@ -17,6 +17,12 @@ export * from './AutoComplete';
 export * from './FormField';
 export * from './Modal';
 export * from './DataGrid';
+/**
+ * Responsive column model shared by every grid-like component. Exported from
+ * the Base layer so Remote and Smart grids inherit it by composition rather
+ * than by a second implementation.
+ */
+export type { GridResponsiveOptions, ResponsiveColumnBehavior, ResponsiveColumnRule, } from './dataGridResponsive';
 export * from './Pagination';
 export * from './Button';
 export * from './Spinner';
@@ -53,10 +59,47 @@ export * from './IconButton';
 export * from './ListItem';
 export * from './Sparkline';
 export * from './Statistic';
+/**
+ * Chart family (doc: full-size Line/Area/Bar/StackedBar/Donut/Pie, distinct
+ * from the compact `Sparkline`). `Chart` is the shared responsive/status
+ * shell every concrete chart composes and is itself public for a consumer
+ * building a custom visualization; `ChartLegend` is the shared series legend.
+ * The per-chart-type render logic (`chart/*Base.tsx`) stays internal.
+ */
+export { Chart } from './Chart';
+export type { ChartProps } from './Chart';
+export { ChartLegend, legendItemsFromSeries } from './ChartLegend';
+export type { ChartLegendItem, ChartLegendProps } from './ChartLegend';
+export { LineChart } from './LineChart';
+export type { LineChartProps } from './LineChart';
+export { AreaChart } from './AreaChart';
+export type { AreaChartProps } from './AreaChart';
+export { BarChart } from './BarChart';
+export type { BarChartProps } from './BarChart';
+export { StackedBarChart } from './StackedBarChart';
+export type { StackedBarChartProps } from './StackedBarChart';
+export { DonutChart } from './DonutChart';
+export type { DonutChartProps } from './DonutChart';
+export { PieChart } from './PieChart';
+export type { PieChartProps } from './PieChart';
+export type { ChartCommonProps, ChartDatum, ChartInteraction, ChartSeries, ChartSliceInteraction, ChartStatusProps, ChartTone, ChartValue, } from './chart/chartTypes';
+export { Calendar } from './Calendar';
+export type { CalendarEvent, CalendarEventVariant, CalendarProps, CalendarView } from './Calendar';
+export { DocumentViewer } from './DocumentViewer';
+export type { DocumentViewerError, DocumentViewerErrorKind, DocumentViewerLabels, DocumentViewerProps, DocumentViewerSource, } from './DocumentViewer';
 export { AppearanceProvider, useAppearance, createAppearanceInitScript, THEME_MODES, SIDEBAR_PRESENTATIONS, SIDEBAR_TONES } from './Appearance';
 export type { AppearanceContextValue, AppearanceInitScriptOptions, AppearanceProviderProps, AppearanceSettings, AppearanceStorage, ResolvedTheme, SidebarPresentation, SidebarTone, ThemeMode, } from './Appearance';
 export * from './appearanceSchemes';
 export * from './AppearanceMenu';
+/**
+ * Context menu system. `RichComponentBase` and the `ContextMenu` compound are
+ * the whole public surface — the surface context, the positioning helpers and
+ * the node-kind model behind them stay internal.
+ */
+export { RichComponentBase } from './RichComponentBase';
+export type { RichComponentBaseProps, RichComponentBaseTrigger } from './RichComponentBase';
+export { ContextMenu } from './ContextMenu';
+export type { ContextMenuComponent, ContextMenuItemProps, ContextMenuLabelProps, ContextMenuProps, ContextMenuSeparatorProps, ContextMenuSubMenuProps, } from './ContextMenu';
 export { Popup } from './shared/Popup';
 export type { PopupProps } from './shared/Popup';
 export { Label } from './shared/Label';

package/dist/base/shared/Portal.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+export interface PortalProps {
+    children: ReactNode;
+    /** Defaults to `document.body` once mounted on the client. */
+    container?: Element | null;
+}
+/**
+ * Minimal SSR-safe portal.
+ *
+ * The repository had no portal infrastructure before this (Popup positions
+ * itself with plain CSS and Modal renders in place, both of which say so in
+ * their own doc comments), so this is the smallest primitive that lets an
+ * overlay escape an ancestor's `overflow`/`transform` clipping.
+ *
+ * `document` is never touched during module initialization or during render:
+ * the host is resolved in an effect, so a server render produces nothing and
+ * the first client render is identical to it. Intentionally internal — it is
+ * plumbing for the context menu surface, not a second public overlay API.
+ */
+export declare function Portal({ children, container }: PortalProps): import('react').ReactPortal | null;

package/dist/base/shared/composeRefs.d.ts

@@ -0,0 +1,3 @@
+import { Ref } from 'react';
+/** Fans one element out to every supplied ref, ignoring the empty ones. */
+export declare function composeRefs<T>(...refs: Array<Ref<T> | undefined | null>): Ref<T>;

package/dist/base/shared/useElementResize.d.ts

@@ -0,0 +1,16 @@
+import { RefObject } from 'react';
+/**
+ * Calls `onResize` whenever the observed element's box changes.
+ *
+ * The element's *own* box, not the viewport: a grid can sit in a narrow
+ * dashboard panel, a modal, a split view or a resizable container, and a
+ * global breakpoint knows nothing about any of those.
+ *
+ * `ResizeObserver` is used when the environment has it, and only then; the
+ * window-resize listener is a fallback for environments without it, so a
+ * modern browser never gets a permanent global listener per grid. Nothing is
+ * touched during module initialization or during render, so importing this on
+ * a server is inert, and the observer is disconnected on cleanup — which is
+ * also what makes it safe under React Strict Mode's double mount.
+ */
+export declare function useElementResize(ref: RefObject<Element | null>, enabled: boolean, onResize: () => void): void;

package/dist/base/shared/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,12 @@
+import { useEffect } from 'react';
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server.
+ *
+ * Measurement has to happen after layout but before paint, which is what
+ * `useLayoutEffect` is for — but React warns when it runs during server
+ * rendering, where there is no layout to read. The `typeof window` test never
+ * touches a browser global (it cannot throw) and is evaluated once, so the
+ * choice is constant for the lifetime of the module and the rules of hooks
+ * still hold.
+ */
+export declare const useIsomorphicLayoutEffect: typeof useEffect;