themelia-react-ui 0.0.0-stage → 1.0.1

package/dist/components/blocks/data-display/dense-info-card/types.d.ts

@@ -0,0 +1,183 @@
+import { type ReactNode } from 'react';
+import type { ActionMenuAction } from '../../../base/action-menu';
+import type { SemanticTone } from '../../../../lib/component-vocabulary';
+import type { StringsProp } from '../../../../lib/strings';
+import type { DenseInfoStrings } from './dense-info.strings';
+export type DenseInfoBadgeTone = SemanticTone;
+export interface DashboardStatusBadge {
+    /** Display label. */
+    label: string;
+    tone: DenseInfoBadgeTone;
+}
+export interface DashboardKeyValueRow {
+    /** Display label. */
+    label: string;
+    value?: string;
+    /** Chip rendered beside the label. */
+    badge?: string;
+    badgeTone?: DenseInfoBadgeTone;
+}
+export interface DenseInfoDashboardProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    /** Chips shown beside the title. */
+    statusBadges: DashboardStatusBadge[];
+    /** Rows to render. */
+    rows: DashboardKeyValueRow[];
+    /** Supporting rows under the primary content. */
+    secondaryRows?: DashboardKeyValueRow[];
+    /** Gauge configuration for the card's headline figure. */
+    scale?: {
+        label: string;
+        value: number;
+        max?: number;
+    };
+    /** Chips in the card footer. */
+    footerBadges?: DashboardStatusBadge[];
+    /** Muted text in the card footer. */
+    footerText?: ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface ClassificationStat {
+    /** Display label. */
+    label: string;
+    value: string;
+    trendBadge?: string;
+    trendTone?: DenseInfoBadgeTone;
+}
+export interface ClassificationRow {
+    /** Display label. */
+    label: string;
+    value: string;
+    dotColor: string;
+    /** Chip rendered beside the label. */
+    badge?: string;
+    badgeTone?: DenseInfoBadgeTone;
+}
+export interface DenseInfoClassificationProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    /** Headline figures shown across the top. */
+    stats: ClassificationStat[];
+    /** Rows making up the card body. */
+    items: ClassificationRow[];
+    /** Caption for the total row. */
+    totalLabel?: string;
+    /** Formatted total. */
+    totalValue?: string;
+    /** Chips in the card footer. */
+    footerBadges?: DashboardStatusBadge[];
+    /** Muted text in the card footer. */
+    footerText?: ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface's own copy. */
+    strings?: StringsProp<DenseInfoStrings>;
+}
+export interface FinancialHeaderBadge {
+    /** Display label. */
+    label: string;
+    tone: DenseInfoBadgeTone;
+}
+export interface FinancialLineItem {
+    /** Display label. */
+    label: string;
+    amount: string;
+    /** Chip rendered beside the label. */
+    badge?: string;
+    badgeTone?: DenseInfoBadgeTone;
+}
+export interface DenseInfoFinancialProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    /** Chips shown in the card header. */
+    headerBadges: FinancialHeaderBadge[];
+    /** Individual amounts making up the total. */
+    lineItems: FinancialLineItem[];
+    /** Caption for the total row. */
+    totalLabel?: string;
+    /** Formatted total. */
+    totalAmount?: string;
+    /** Chips in the card footer. */
+    footerBadges?: FinancialHeaderBadge[];
+    /** Muted text in the card footer. */
+    footerText?: ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface's own copy. */
+    strings?: StringsProp<DenseInfoStrings>;
+}
+export interface ProjectMetaPair {
+    /** Leading glyph. */
+    icon?: ReactNode;
+    /** Display label. */
+    label: string;
+}
+export interface DenseInfoProjectCardProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    /** Current state, shown as a chip. */
+    statusLabel: string;
+    /** Badge tone for the status chip. */
+    statusTone: DenseInfoBadgeTone;
+    /** Label/value facts under the title. */
+    metaPairs?: ProjectMetaPair[];
+    /** Formatted date for the entry. */
+    date?: string;
+    /** Priority level, shown as a chip. */
+    priority?: string;
+    /** Tasks finished so far. */
+    completedTasks: number;
+    /** Tasks in the project overall. */
+    totalTasks: number;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface's own copy. */
+    strings?: StringsProp<DenseInfoStrings>;
+}
+export interface ScoreKeyValueRow {
+    /** Display label. */
+    label: string;
+    value: string;
+}
+export interface DenseInfoScoreCardProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    /** Chips shown beside the title. */
+    statusBadges: DashboardStatusBadge[];
+    /** Headline score for the card. */
+    score: number;
+    /** Band the score falls into, driving its tone. */
+    scoreLevel: 'good' | 'medium' | 'low';
+    /** How many score segments are filled. */
+    scoreFilled: number;
+    /** How many score segments exist in total. */
+    scoreTotal?: number;
+    /** Rows to render. */
+    rows: ScoreKeyValueRow[];
+    /** Chips in the card footer. */
+    footerBadges?: DashboardStatusBadge[];
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Merged onto the outermost node. */
+    className?: string;
+}

package/dist/components/blocks/data-display/empty-state/empty-state.d.ts

@@ -0,0 +1,2 @@
+import type { EmptyStateProps } from './empty-state.types';
+export declare const EmptyState: import("react").ForwardRefExoticComponent<EmptyStateProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/blocks/data-display/empty-state/empty-state.strings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Strings for `<EmptyState>`. English defaults — every piece of copy is
+ * deep-merge-overridable per rule 8.
+ *
+ * `title`/`description` here are the *fallback* defaults the component
+ * renders when neither the prop nor a per-illustration preset supplies
+ * its own copy. In practice, the consumer usually passes an explicit
+ * `title` / `description` per resource ("No products", "No invoices yet")
+ * — these defaults exist so a bare `<EmptyState />` still renders
+ * sensibly during scaffolding.
+ */
+export interface EmptyStateStrings {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description: string;
+    ariaLabel: string;
+}
+export declare const defaultEmptyStateStrings: EmptyStateStrings;

package/dist/components/blocks/data-display/empty-state/empty-state.types.d.ts

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react';
+import type { ComponentScale } from '../../../../lib/component-vocabulary';
+import type { StringsProp } from '../../../../lib/strings';
+import type { EmptyStateStrings } from './empty-state.strings';
+/**
+ * Vertical breathing room.
+ *
+ * `sm` — compact cards, table cells, and side panels.
+ * `md` — normal table, list, and card empty states.
+ * `lg` — large page-level empty states.
+ */
+export type EmptyStatePadding = ComponentScale;
+/**
+ * How the `media` slot renders.
+ *
+ * `none`         — render `media` raw (illustrations bring their own canvas).
+ * `icon`         — wrap `media` in a 40px square with `bg-muted` rounded-radius
+ *                  (good for a single Lucide icon).
+ * `icon-soft`    — same as `icon` but with a softer tone wash; pairs with
+ *                  a neutral tone for a calmer palette.
+ * `illustration` — center an illustration with no chrome and a
+ *                  comfortable max-width.
+ */
+export type EmptyStateMediaVariant = 'none' | 'icon' | 'icon-soft' | 'illustration';
+/**
+ * Render context passed to the `renderMedia` render-prop, useful for
+ * consumers wanting to react to size / variant.
+ */
+export interface EmptyStateRenderMediaContext {
+    mediaVariant: EmptyStateMediaVariant;
+}
+export interface EmptyStateProps {
+    /**
+     * Headline — typically the resource name in negative form
+     * ("No products", "No invoices yet"). Falls back to `strings.title`.
+     */
+    title?: ReactNode;
+    /**
+     * Supporting description. Keep it to 1–2 sentences. Falls back to
+     * `strings.description`. Pass `false` to hide entirely (when the title
+     * alone tells the story).
+     */
+    description?: ReactNode | false;
+    /**
+     * The visual: an illustration (use `partials/illustrations/*` or your
+     * own SVG), a Lucide icon, or any ReactNode.
+     */
+    media?: ReactNode;
+    /**
+     * Controls the chrome around `media`. Defaults to `'none'`. See
+     * `EmptyStateMediaVariant`.
+     */
+    mediaVariant?: EmptyStateMediaVariant;
+    /**
+     * Render-prop alternative to `media` — receives a context so consumers
+     * can drive a fully custom illustration based on the variant.
+     */
+    renderMedia?: (ctx: EmptyStateRenderMediaContext) => ReactNode;
+    /**
+     * Primary actions (typically a `<Button>`) shown directly under the
+     * description. Multiple actions inherit the semantic compact action gap.
+     */
+    actions?: ReactNode;
+    /**
+     * Secondary content under the actions — small text, learn-more link,
+     * keyboard hints, etc.
+     */
+    footer?: ReactNode;
+    /** Vertical breathing. Defaults to the provider density scale; tune values through CSS variables. */
+    padding?: EmptyStatePadding;
+    /**
+     * `border` toggles the dashed-border look on/off. Defaults to `false`
+     * (no border) — reach for `true` when the empty state replaces a
+     * card body and you want the dashed-zone affordance.
+     */
+    border?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** All copy is overridable via the strings prop, deep-merged. */
+    strings?: StringsProp<EmptyStateStrings>;
+    /**
+     * Optional aria-label on the wrapper. Defaults to `strings.ariaLabel`
+     * which itself defaults to "Empty state".
+     */
+    ariaLabel?: string;
+}

package/dist/components/blocks/data-display/empty-state/index.d.ts

@@ -0,0 +1,5 @@
+export { EmptyState } from './empty-state';
+export { defaultEmptyStateStrings, type EmptyStateStrings, } from './empty-state.strings';
+export type { EmptyStateMediaVariant, EmptyStatePadding, EmptyStateProps, EmptyStateRenderMediaContext, } from './empty-state.types';
+export { DocumentStackIllustration, InboxCleanIllustration, SearchGlassIllustration, StackedCardsIllustration, UsersCircleIllustration, } from './partials/illustrations';
+export type { EmptyStateIllustrationProps } from './partials/illustrations';

package/dist/components/blocks/data-display/empty-state/partials/illustrations/document-stack.d.ts

@@ -0,0 +1,9 @@
+import type { EmptyStateIllustrationProps } from './types';
+/**
+ * Two staggered document silhouettes — for "no documents", "no
+ * invoices", "no reports" surfaces.
+ */
+export declare function DocumentStackIllustration({ className }: EmptyStateIllustrationProps): import("react").JSX.Element;
+export declare namespace DocumentStackIllustration {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/empty-state/partials/illustrations/inbox-clean.d.ts

@@ -0,0 +1,9 @@
+import type { EmptyStateIllustrationProps } from './types';
+/**
+ * Open inbox tray with a soft check above — for "all caught up",
+ * "no notifications", "inbox zero" surfaces.
+ */
+export declare function InboxCleanIllustration({ className }: EmptyStateIllustrationProps): import("react").JSX.Element;
+export declare namespace InboxCleanIllustration {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/empty-state/partials/illustrations/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Token-driven illustrations for `<EmptyState>`.
+ *
+ * Each illustration is a small composition of `bg-muted` /
+ * `bg-background` / `border-border` divs (no raw palette colors), so it
+ * adapts to the consumer's theme automatically. Use as the `media`
+ * prop of `<EmptyState>` — pick one per resource:
+ *
+ *     <EmptyState
+ *         media={<StackedCardsIllustration />}
+ *         title="No products yet"
+ *         description="Add your first product to start selling."
+ *         actions={<Button>Add product</Button>}
+ *     />
+ *
+ * Add new illustrations by dropping a new file in this folder and
+ * re-exporting it here. Keep them framework-agnostic and
+ * token-driven — never reach for raw color literals.
+ */
+export { DocumentStackIllustration } from './document-stack';
+export { InboxCleanIllustration } from './inbox-clean';
+export { SearchGlassIllustration } from './search-glass';
+export { StackedCardsIllustration } from './stacked-cards';
+export { UsersCircleIllustration } from './users-circle';
+export type { EmptyStateIllustrationProps } from './types';

package/dist/components/blocks/data-display/empty-state/partials/illustrations/search-glass.d.ts

@@ -0,0 +1,9 @@
+import type { EmptyStateIllustrationProps } from './types';
+/**
+ * Magnifying-glass illustration centered on a soft tinted disk — for
+ * "no search results", "nothing matches your filters" surfaces.
+ */
+export declare function SearchGlassIllustration({ className }: EmptyStateIllustrationProps): import("react").JSX.Element;
+export declare namespace SearchGlassIllustration {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/empty-state/partials/illustrations/stacked-cards.d.ts

@@ -0,0 +1,11 @@
+import type { EmptyStateIllustrationProps } from './types';
+/**
+ * Three stacked card silhouettes with a fade-out at the bottom — the
+ * generic "no records" illustration. Token-driven so it adapts to any
+ * theme (uses `bg-muted`, `bg-background`, `border-border`, no raw
+ * palette).
+ */
+export declare function StackedCardsIllustration({ className }: EmptyStateIllustrationProps): import("react").JSX.Element;
+export declare namespace StackedCardsIllustration {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/empty-state/partials/illustrations/types.d.ts

@@ -0,0 +1,4 @@
+export interface EmptyStateIllustrationProps {
+    /** Merged onto the outermost node. */
+    className?: string;
+}

package/dist/components/blocks/data-display/empty-state/partials/illustrations/users-circle.d.ts

@@ -0,0 +1,9 @@
+import type { EmptyStateIllustrationProps } from './types';
+/**
+ * Three overlapping avatar circles — for "no team members", "no
+ * customers", "no contributors" surfaces.
+ */
+export declare function UsersCircleIllustration({ className }: EmptyStateIllustrationProps): import("react").JSX.Element;
+export declare namespace UsersCircleIllustration {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/index.d.ts

@@ -0,0 +1,6 @@
+export type { DenseInfoBadgeTone, DashboardStatusBadge, DashboardKeyValueRow, DenseInfoDashboardProps, ClassificationStat, ClassificationRow, DenseInfoClassificationProps, FinancialHeaderBadge, FinancialLineItem, DenseInfoFinancialProps, ProjectMetaPair, DenseInfoProjectCardProps, ScoreKeyValueRow, DenseInfoScoreCardProps, DenseInfoStrings, } from './dense-info-card';
+export { defaultDenseInfoStrings, DenseInfoDashboard, DenseInfoClassification, DenseInfoFinancial, DenseInfoProjectCard, DenseInfoScoreCard, } from './dense-info-card';
+export * from './empty-state';
+export * from './metadata';
+export { RelationshipCardFrame, type RelationshipCardFrameProps, } from './relationship-card-frame';
+export * from './inline-stat';

package/dist/components/blocks/data-display/inline-stat/index.d.ts

@@ -0,0 +1 @@
+export { InlineStat, type InlineStatProps, type InlineStatLayout } from './inline-stat';

package/dist/components/blocks/data-display/inline-stat/inline-stat.d.ts

@@ -0,0 +1,35 @@
+/**
+ * InlineStat — label + value pair, the workhorse of detail panels and card
+ * footers. Three layouts:
+ *
+ *  - `between` (default): label and value pushed to opposite ends of the row.
+ *  - `inline`: label sits immediately before the value, separator-style.
+ *  - `stacked`: label above (xs secondary), value below (md).
+ *
+ * `mono` toggles `tabular-nums` on the value side for amounts and counters.
+ * Use `valueClassName` for one-off colour/weight overrides; the surrounding
+ * row is intentionally plain so consumers can stack many of these without
+ * visual clutter.
+ */
+import type { ReactNode } from 'react';
+export type InlineStatLayout = 'between' | 'inline' | 'stacked';
+export interface InlineStatProps {
+    /** Display label. Scalar labels use DisplayLabel; rich content owns its typography. */
+    label: ReactNode;
+    /** The figure to show. */
+    value: ReactNode;
+    /** Whether the label sits above the value or beside it. */
+    layout?: InlineStatLayout;
+    /** Renders the value in tabular monospace figures. */
+    mono?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Merged onto the label. */
+    labelClassName?: string;
+    /** Merged onto the value. */
+    valueClassName?: string;
+}
+export declare function InlineStat({ label, value, layout, mono, className, labelClassName, valueClassName, }: InlineStatProps): import("react").JSX.Element;
+export declare namespace InlineStat {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/metadata/index.d.ts

@@ -0,0 +1,4 @@
+export { MetadataList } from './metadata-list';
+export type { MetadataDensity, MetadataInlineListItem, MetadataLayout, MetadataListItem, MetadataListProps, } from './metadata-list';
+export { MetadataValue } from './metadata-value';
+export type { MetadataValueDescriptor, MetadataValueKind, MetadataValueProps, } from './metadata-value';

package/dist/components/blocks/data-display/metadata/metadata-list.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MetadataList — flexible label/value list for entity metadata.
+ *
+ * Three layouts:
+ *  - `grid` (default): label-on-top, value-below cells for entity details.
+ *  - `rows`: two-column definition rows with hairline separators.
+ *  - `inline`: label/separator/value pairs that wrap, suitable for
+ *    pill-style summaries (e.g. "Created Jan 4 · By Alice · v3.2").
+ *
+ * Each item supports an optional icon, tooltip, React-node value, custom
+ * `render`, and per-item `emptyLabel`. Falls back to the shared `EMPTY` when
+ * both are missing. Returns `null` when the list is empty so callers can render
+ * unconditionally.
+ */
+import { type LucideIcon } from 'lucide-react';
+import React from 'react';
+import { type ResponsiveValue } from '../../../base/structure';
+import { type StringsProp } from '../../../../lib/strings';
+import { defaultMetadataListStrings, type MetadataListStrings } from './metadata-list.strings';
+import { type MetadataValueDescriptor } from './metadata-value';
+export type { MetadataListStrings };
+export { defaultMetadataListStrings };
+export type MetadataListItem = {
+    /** Stable identity for this entry. */
+    id?: string;
+    /** Display label. */
+    label: React.ReactNode;
+    value?: React.ReactNode | MetadataValueDescriptor | null;
+    /** Supporting copy shown under the label. */
+    description?: React.ReactNode | null;
+    tooltip?: React.ReactNode;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    emptyLabel?: React.ReactNode;
+    render?: (item: MetadataListItem) => React.ReactNode;
+};
+export type MetadataInlineListItem = Omit<MetadataListItem, 'description'> & {
+    description?: never;
+};
+export type MetadataLayout = 'grid' | 'rows' | 'inline';
+export type MetadataDensity = 'default' | 'compact';
+type MetadataListSharedProps = {
+    /** How many columns the grid layout uses. Accepts a per-breakpoint value. */
+    columns?: ResponsiveValue<1 | 2 | 3 | 4>;
+    /** Row spacing. `compact` tightens the list for dense panels. */
+    density?: MetadataDensity;
+    /** Copy shown for an item whose value is empty. Defaults to an em dash. */
+    emptyLabel?: React.ReactNode;
+    /** Surface title. */
+    title?: React.ReactNode;
+    /** Draws a rule between the title and the first item. */
+    titleSeparator?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Character placed between a label and its value. Defaults to a colon. */
+    separator?: string;
+    /** Divider between items — `true` for the default rule, or a character for inline layouts. */
+    itemSeparator?: boolean | string;
+    /** Per-instance string overrides (deep-merged over `defaultMetadataListStrings`). */
+    strings?: StringsProp<MetadataListStrings>;
+};
+type MetadataGridRowsProps = MetadataListSharedProps & {
+    /** Label/value pairs to render. */
+    items: MetadataListItem[];
+    /** `grid` flows items into `columns`; `rows` stacks them one per line. Default: `grid`. */
+    layout?: 'grid' | 'rows';
+};
+type MetadataInlineProps = MetadataListSharedProps & {
+    /** Values to render, without labels. */
+    items: MetadataInlineListItem[];
+    /** Runs the values together on one line, separated by `itemSeparator`. */
+    layout: 'inline';
+};
+export type MetadataListProps = MetadataGridRowsProps | MetadataInlineProps;
+export declare function MetadataList({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, strings: stringsProp, }: MetadataListProps): React.JSX.Element | null;
+export declare namespace MetadataList {
+    var displayName: string;
+}

package/dist/components/blocks/data-display/metadata/metadata-list.strings.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Default user-facing strings for `<MetadataList>`.
+ *
+ * Consumers wire backend i18n at the call site:
+ *
+ *   <MetadataList strings={{ infoFallback: t('metadata.info') }} … />
+ */
+export interface MetadataListStrings {
+    /**
+     * Suffix appended to the label when generating the tooltip-trigger
+     * `aria-label` ("<label> info"). Receives the label as the first arg
+     * so consumers can localise the full template.
+     */
+    formatInfoAriaLabel: (label: string) => string;
+    /** Fallback `aria-label` used when the field label is not a plain string. */
+    infoFallback: string;
+}
+export declare const defaultMetadataListStrings: MetadataListStrings;