@ceebee/ui 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,417 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Joins class names, dropping falsy values. No merge logic: the library never emits
+ *  conflicting utility classes, so the "last wins" problem tailwind-merge solves does not exist. */
+declare function cn(...parts: Array<string | false | null | undefined>): string;
+type Tone = 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'danger';
+type Size = 'sm' | 'md' | 'lg';
+type DecorHue = 'violet' | 'blue' | 'teal' | 'green' | 'amber' | 'rose';
+
+type SurfaceVariant = 'plain' | 'tinted' | 'glass' | 'gradient';
+interface SurfaceProps {
+    variant?: SurfaceVariant;
+    /** Semantic colour for `tinted`; ignored by `plain`. */
+    tone?: Tone;
+    /** Decorative hue for `tinted` / `gradient` — the pastel card set. Wins over `tone`. */
+    hue?: DecorHue;
+    elevation?: 'none' | 'sm' | 'md' | 'lg';
+    radius?: 'sm' | 'md' | 'lg' | 'xl';
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    bordered?: boolean;
+    className?: string;
+    children?: ReactNode;
+    /** Renders a different element; the library ships no polymorphic `as` beyond this. */
+    asSection?: boolean;
+}
+/**
+ * The panel every raised or tinted thing is built on. Glass and gradient live here as
+ * variants rather than being baked into the brand (ADR 0002), so one Skin reproduces the
+ * reference board and another produces something sober without touching a component.
+ */
+declare function Surface({ variant, tone, hue, elevation, radius, padding, bordered, className, children, asSection, }: SurfaceProps): react.JSX.Element;
+
+type SpaceStep = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+interface StackProps {
+    direction?: 'row' | 'column';
+    gap?: SpaceStep;
+    align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    justify?: 'start' | 'center' | 'end' | 'between';
+    wrap?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+/** Flex layout whose gap can only be a spacing token — the reason the library has no raw padding. */
+declare function Stack({ direction, gap, align, justify, wrap, className, children, }: StackProps): react.JSX.Element;
+interface GridProps {
+    /** Column count at the widest breakpoint; the grid collapses on its own below it. */
+    columns?: 1 | 2 | 3 | 4 | 6 | 12;
+    gap?: SpaceStep;
+    minItemWidth?: string;
+    className?: string;
+    children?: ReactNode;
+}
+declare function Grid({ columns, gap, minItemWidth, className, children }: GridProps): react.JSX.Element;
+interface ContainerProps {
+    size?: 'sm' | 'md' | 'lg' | 'full';
+    className?: string;
+    children?: ReactNode;
+}
+declare function Container({ size, className, children }: ContainerProps): react.JSX.Element;
+
+interface TextProps {
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    tone?: Tone | 'muted' | 'subtle';
+    weight?: 'regular' | 'medium' | 'semibold';
+    as?: 'p' | 'span' | 'div';
+    numeric?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+declare function Text({ size, tone, weight, as: Tag, numeric, className, children, }: TextProps): react.JSX.Element;
+interface HeadingProps {
+    level?: 1 | 2 | 3 | 4;
+    size?: 'lg' | 'xl' | '2xl' | '3xl';
+    className?: string;
+    children?: ReactNode;
+}
+/** Level and size are separate on purpose: document structure is not a font size. */
+declare function Heading({ level, size, className, children }: HeadingProps): react.JSX.Element;
+
+interface BadgeProps {
+    children: ReactNode;
+    tone?: Tone;
+    variant?: 'soft' | 'solid' | 'outline';
+    size?: 'sm' | 'md';
+    /** Leading dot — for status, where the colour alone would be the only signal. */
+    dot?: boolean;
+    className?: string;
+}
+/** A label, not a button. If it can be clicked or removed, it is a Tag and needs a control. */
+declare function Badge({ children, tone, variant, size, dot, className }: BadgeProps): react.JSX.Element;
+
+interface EmptyStateProps {
+    title: ReactNode;
+    description?: ReactNode;
+    icon?: ReactNode;
+    actions?: ReactNode;
+    /** `search` reads as "nothing matched", `first-run` as "nothing here yet" — they differ. */
+    variant?: 'first-run' | 'search' | 'error';
+    className?: string;
+}
+declare function EmptyState({ title, description, icon, actions, variant, className }: EmptyStateProps): react.JSX.Element;
+
+interface SpinnerProps {
+    size?: 'sm' | 'md' | 'lg';
+    tone?: Tone;
+    /** Accessible name. Omit only when a nearby live region already says what is loading. */
+    label?: string;
+    className?: string;
+}
+/** Server-safe: a CSS animation, no state. It stops turning under reduced motion. */
+declare function Spinner({ size, tone, label, className }: SpinnerProps): react.JSX.Element;
+interface ProgressBarProps {
+    /** Omit for an indeterminate bar — "something is happening, duration unknown". */
+    value?: number;
+    max?: number;
+    tone?: Tone;
+    size?: 'sm' | 'md';
+    label: string;
+    /** Prints the percentage at the end of the track. */
+    showValue?: boolean;
+    className?: string;
+}
+declare function ProgressBar({ value, max, tone, size, label, showValue, className }: ProgressBarProps): react.JSX.Element;
+
+interface TimelineEntry {
+    /** When it happened. Already formatted — the library does not decide date format. */
+    time: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    icon?: ReactNode;
+    tone?: Tone;
+}
+interface TimelineProps {
+    entries: TimelineEntry[];
+    className?: string;
+}
+/**
+ * An ordered list of things that happened. Server-safe, and an `<ol>` rather than divs, so the
+ * order is a fact a screen reader reads out rather than a visual convention.
+ */
+declare function TimelineRoot({ entries, className }: TimelineProps): react.JSX.Element;
+interface TimelineSkeletonProps {
+    entries?: number;
+    className?: string;
+}
+declare function TimelineSkeleton({ entries, className }: TimelineSkeletonProps): react.JSX.Element;
+declare const Timeline: typeof TimelineRoot & {
+    Skeleton: typeof TimelineSkeleton;
+};
+
+interface SkeletonProps {
+    width?: string;
+    height?: string;
+    radius?: 'sm' | 'md' | 'lg' | 'full';
+    className?: string;
+}
+declare function box({ width, height, radius, className }: SkeletonProps): react.JSX.Element;
+interface SkeletonTextProps {
+    lines?: number;
+    /** Width of the last line, which is short in real text and should be short here too. */
+    lastLineWidth?: string;
+    className?: string;
+}
+declare function text({ lines, lastLineWidth, className }: SkeletonTextProps): react.JSX.Element;
+declare function circle({ size, className }: {
+    size?: string;
+    className?: string;
+}): react.JSX.Element;
+/**
+ * Placeholder shapes. Free-form cases use these; every Composition also ships its own
+ * `.Skeleton` built from the same tokens as the real thing, so the two cannot drift (ADR 0009).
+ */
+declare const Skeleton: typeof box & {
+    Text: typeof text;
+    Circle: typeof circle;
+    Rect: typeof box;
+};
+
+interface ProgressRingProps {
+    value: number;
+    max?: number;
+    size?: number;
+    thickness?: number;
+    tone?: Tone;
+    hue?: DecorHue;
+    /** Content in the middle of the ring. Defaults to the rounded percentage. */
+    children?: ReactNode;
+    /** Accessible name; required because a bare percentage tells a screen reader nothing. */
+    label: string;
+    className?: string;
+}
+/**
+ * The 84%-style ring the reference board leans on. Hand-written SVG, no charting
+ * dependency — it has no axis and no scale, so it is a Widget, not a Chart (ADR 0007).
+ */
+declare function ProgressRing({ value, max, size, thickness, tone, hue, children, label, className, }: ProgressRingProps): react.JSX.Element;
+
+/** The ring's geometry, kept out of the component so it can be asserted (ADR 0012). */
+interface RingGeometry {
+    radius: number;
+    circumference: number;
+    /** Stroke offset that renders `value` of `max` as a filled arc. */
+    dashOffset: number;
+    /** Value clamped into range, for the accessible label and the printed number. */
+    clamped: number;
+}
+declare function ringGeometry(value: number, max: number, size: number, thickness: number): RingGeometry;
+
+/** Donut arithmetic, kept pure so the awkward inputs are asserted (ADR 0012). */
+interface DonutSlice {
+    value: number;
+    label: string;
+}
+interface DonutArc extends DonutSlice {
+    /** Fraction of the whole, 0–1. */
+    fraction: number;
+    /** Stroke dash length for this arc, in circumference units. */
+    length: number;
+    /** Stroke dash offset that positions it after the arcs before it. */
+    offset: number;
+    index: number;
+}
+/**
+ * Turns values into arcs. Negative values are dropped rather than drawn backwards, and a set
+ * that sums to zero produces no arcs at all instead of dividing by it.
+ */
+declare function donutArcs(slices: DonutSlice[], circumference: number): DonutArc[];
+
+interface DonutProps {
+    slices: DonutSlice[];
+    size?: number;
+    thickness?: number;
+    /** Colour per slice, in order. Falls back to the decorative palette. */
+    hues?: DecorHue[];
+    /** Content in the hole — a total, usually. */
+    children?: React.ReactNode;
+    label: string;
+    className?: string;
+}
+/** A proportion widget, not a chart: no axis, no scale, no tooltip (ADR 0007). */
+declare function Donut({ slices, size, thickness, hues, children, label, className }: DonutProps): react.JSX.Element;
+
+interface SparklineProps {
+    values: number[];
+    width?: number;
+    height?: number;
+    tone?: Tone;
+    hue?: DecorHue;
+    /** Fills under the line. Use it when the shape matters more than the exact values. */
+    filled?: boolean;
+    /** Marks the final point — the "where it ended up" dot. */
+    showLast?: boolean;
+    label: string;
+    className?: string;
+}
+/** Trend at a glance. No axis, no scale, so it is a Widget rather than a Chart (ADR 0007). */
+declare function Sparkline({ values, width, height, tone, hue, filled, showLast, label, className, }: SparklineProps): react.JSX.Element;
+interface BarMiniProps {
+    values: number[];
+    width?: number;
+    height?: number;
+    tone?: Tone;
+    hue?: DecorHue;
+    label: string;
+    className?: string;
+}
+/** The same idea in bars, for counts rather than a continuous series. */
+declare function BarMini({ values, width, height, tone, hue, label, className }: BarMiniProps): react.JSX.Element;
+
+/** Sparkline geometry. Pure, because an off-by-one here silently draws a wrong shape. */
+interface SparklineGeometry {
+    /** `M…L…` path through every point. Empty when there is nothing to draw. */
+    line: string;
+    /** The same path closed along the baseline, for the filled variant. */
+    area: string;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+declare function sparklineGeometry(values: number[], width: number, height: number, padding?: number): SparklineGeometry;
+
+interface LeaderboardEntry {
+    id: string;
+    name: string;
+    /** Already formatted — the library does not decide what a score looks like. */
+    score: ReactNode;
+    avatarSrc?: string;
+    detail?: ReactNode;
+    /** Movement since the last ranking. */
+    delta?: {
+        value: string;
+        direction: 'up' | 'down' | 'flat';
+    };
+    /** Marks the viewer's own row, wherever it sits. */
+    you?: boolean;
+    hue?: DecorHue;
+}
+interface LeaderboardProps {
+    entries: LeaderboardEntry[];
+    /** Names the list; required, because a bare ranked list says nothing on its own. */
+    label: string;
+    /** Ranks 1–3 get a medal tint. Turn it off for a plain ranked list. */
+    medals?: boolean;
+    className?: string;
+}
+/**
+ * A ranked list — the gamified board pattern. Server-safe, and an `<ol>`, so the ranking is a
+ * fact a screen reader reads out rather than a column of numbers it has to infer.
+ */
+declare function LeaderboardRoot({ entries, label, medals, className }: LeaderboardProps): react.JSX.Element;
+interface LeaderboardSkeletonProps {
+    rows?: number;
+    className?: string;
+}
+/** Same row geometry as the real list, so the panel does not resize on load (ADR 0009). */
+declare function LeaderboardSkeleton({ rows, className }: LeaderboardSkeletonProps): react.JSX.Element;
+declare const Leaderboard: typeof LeaderboardRoot & {
+    Skeleton: typeof LeaderboardSkeleton;
+};
+
+interface AvatarProps {
+    /** The person or thing. Used for the accessible name, the initials, and the fallback hue. */
+    name: string;
+    src?: string;
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /** Overrides the hue derived from the name. */
+    hue?: DecorHue;
+    /** Presence dot. */
+    status?: 'online' | 'busy' | 'away' | 'offline';
+    className?: string;
+}
+/**
+ * Server-safe: no image-load state, no hooks. The initials render underneath and the image
+ * covers them when it loads, so a broken URL degrades to initials without JavaScript.
+ */
+declare function Avatar({ name, src, size, hue, status, className }: AvatarProps): react.JSX.Element;
+interface AvatarGroupProps {
+    children: ReactNode;
+    /** Rendered as "+N" after the stack. */
+    overflow?: number;
+    size?: AvatarProps['size'];
+    className?: string;
+}
+declare function AvatarGroup({ children, overflow, size, className }: AvatarGroupProps): react.JSX.Element;
+
+/**
+ * First letter of the first and last word. Two letters at most, because three stop fitting
+ * in the small size and a clipped initial reads as a rendering bug.
+ */
+declare function initialsOf(name: string): string;
+/** Stable hue per name, so the same person keeps their colour across sessions and devices. */
+declare function hueForName(name: string): DecorHue;
+
+interface Crumb {
+    label: ReactNode;
+    href?: string;
+    onClick?: () => void;
+}
+interface BreadcrumbsProps {
+    items: Crumb[];
+    /** Collapses the middle when the trail is longer than this. */
+    maxItems?: number;
+    className?: string;
+}
+/**
+ * Server-safe. The last crumb is the current page: it is text with `aria-current`, not a link,
+ * because a link to where you already are is a dead end for keyboard and screen reader users.
+ */
+declare function Breadcrumbs({ items, maxItems, className }: BreadcrumbsProps): react.JSX.Element;
+
+interface Step {
+    label: ReactNode;
+    description?: ReactNode;
+}
+interface StepperProps {
+    steps: Step[];
+    /** Zero-based index of the step in progress. */
+    current: number;
+    orientation?: 'horizontal' | 'vertical';
+    className?: string;
+}
+/**
+ * Progress through an ordered sequence — the thing Tabs must not be used for. Server-safe:
+ * it displays position, it does not navigate.
+ */
+declare function Stepper({ steps, current, orientation, className }: StepperProps): react.JSX.Element;
+
+interface StatCardProps {
+    label: string;
+    value: ReactNode;
+    /** Signed change, e.g. `+12.4%`. Direction decides the colour, not the caller. */
+    delta?: {
+        value: string;
+        direction: 'up' | 'down' | 'flat';
+    };
+    caption?: string;
+    hue?: DecorHue;
+    icon?: ReactNode;
+    /** A Widget (ProgressRing, Sparkline) shown to the side. */
+    visual?: ReactNode;
+    className?: string;
+}
+/** The tinted metric tile the reference board repeats on every dashboard. */
+declare function StatCard({ label, value, delta, caption, hue, icon, visual, className }: StatCardProps): react.JSX.Element;
+declare namespace StatCard {
+    var Skeleton: typeof StatCardSkeleton;
+}
+interface StatCardSkeletonProps {
+    withVisual?: boolean;
+    className?: string;
+}
+/** Built from StatCard's own spacing, so the tile does not resize when data arrives (ADR 0009). */
+declare function StatCardSkeleton({ withVisual, className }: StatCardSkeletonProps): react.JSX.Element;
+
+export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, Badge, type BadgeProps, BarMini, type BarMiniProps, Breadcrumbs, type BreadcrumbsProps, Container, type ContainerProps, type Crumb, type DecorHue, Donut, type DonutArc, type DonutProps, type DonutSlice, EmptyState, type EmptyStateProps, Grid, type GridProps, Heading, type HeadingProps, Leaderboard, type LeaderboardEntry, type LeaderboardProps, type LeaderboardSkeletonProps, ProgressBar, type ProgressBarProps, ProgressRing, type ProgressRingProps, type RingGeometry, type Size, Skeleton, type SkeletonProps, type SkeletonTextProps, Sparkline, type SparklineGeometry, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackProps, StatCard, type StatCardProps, type StatCardSkeletonProps, type Step, Stepper, type StepperProps, Surface, type SurfaceProps, type SurfaceVariant, Text, type TextProps, Timeline, type TimelineEntry, type TimelineProps, type TimelineSkeletonProps, type Tone, cn, donutArcs, hueForName, initialsOf, ringGeometry, sparklineGeometry };