@ceebee/ui 0.5.2 → 1.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, AnchorHTMLAttributes, ReactElement } 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. */
@@ -29,7 +29,7 @@ interface SurfaceProps {
 }
 /**
  * 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
+ * variants rather than being baked into the brand, so one Skin reproduces the
  * reference board and another produces something sober without touching a component.
  */
 declare function Surface({ variant, glassStyle, tone, hue, elevation, radius, padding, bordered, className, children, asSection, }: SurfaceProps): react.JSX.Element;
@@ -81,184 +81,32 @@ interface HeadingProps {
 /** 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 LinkButtonProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'color'> {
-    variant?: 'solid' | 'soft' | 'outline' | 'ghost';
-    tone?: Tone;
-    size?: Size;
-    iconStart?: ReactNode;
-    iconEnd?: ReactNode;
-    children?: ReactNode;
-    /**
-     * Render something else in the anchor's place — a router's own Link, which has
-     * to stay itself or client-side navigation is lost. It receives the classes
-     * and the tone; everything else it keeps. The same `render` seam Base UI uses
-     * elsewhere in this library.
-     */
-    render?: ReactElement;
-}
-/**
- * A link wearing a button's clothes.
- *
- * Not a `Button` with an `href`. A link navigates and a button acts, and the
- * difference is not decoration: a link can be opened in a new tab, copied,
- * dragged to a bookmark bar and reached by a screen reader's list of links,
- * while a button can be disabled and submit a form. Those are different
- * contracts, so they are different components (ADR 0014).
- *
- * What they share is the look, and that is shared literally — the same
- * `cb-button` classes rather than a second set that would agree today and drift
- * apart later. It is server-safe: an anchor needs no hook, no handler and no
- * motion, so it stays a Server Component (ADR 0004). The press animation is
- * Button's alone, which is honest: a link does not depress, it goes somewhere.
- */
-declare function LinkButton({ variant, tone, size, iconStart, iconEnd, className, children, render, ...rest }: LinkButtonProps): react.JSX.Element;
-
-interface DividerProps {
-    /** A word or two sitting in the rule, for a section break that names itself. */
-    children?: ReactNode;
-    orientation?: 'horizontal' | 'vertical';
-    className?: string;
-}
-/**
- * A rule between things.
- *
- * `<hr>` when it separates content, because that is what the element means and
- * a screen reader announces it. With a label it becomes a `<div>` carrying the
- * rule in its borders instead — an `<hr>` may not contain anything, and a
- * separator that says which section is starting is worth more than the element.
- */
-declare function Divider({ children, orientation, className }: DividerProps): 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 Empty({ 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 Spin({ 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 {
+interface PageContainerSkeletonProps {
+    breadcrumb?: boolean;
+    subtitle?: boolean;
+    extra?: boolean;
+    tabs?: boolean;
     lines?: number;
-    /** Width of the last line, which is short in real text and should be short here too. */
-    lastLineWidth?: string;
-    className?: string;
+    containerSize?: ContainerProps['size'];
 }
-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;
-};
+declare function PageContainerSkeleton({ breadcrumb, subtitle, extra, tabs, lines, containerSize }: PageContainerSkeletonProps): react.JSX.Element;
 
-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. */
+interface PageContainerProps {
+    breadcrumb?: ReactNode;
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    extra?: ReactNode;
+    tabs?: ReactNode;
     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;
+    containerSize?: ContainerProps['size'];
 }
-declare function ringGeometry(value: number, max: number, size: number, thickness: number): RingGeometry;
+/** Server-safe page frame. Routing, data, title level, action behaviour, and tab state remain external. */
+declare function PageContainerRoot({ breadcrumb, title, subtitle, extra, tabs, children, containerSize }: PageContainerProps): react.JSX.Element;
+declare const PageContainer: typeof PageContainerRoot & {
+    Skeleton: typeof PageContainerSkeleton;
+};
 
-/** Donut arithmetic, kept pure so the awkward inputs are asserted (ADR 0012). */
+/** Donut arithmetic, kept pure so the awkward inputs are asserted. */
 interface DonutSlice {
     value: number;
     label: string;
@@ -289,7 +137,7 @@ interface DonutProps {
     label: string;
     className?: string;
 }
-/** A proportion widget, not a chart: no axis, no scale, no tooltip (ADR 0007). */
+/** A proportion widget, not a chart: no axis, no scale, no tooltip. */
 declare function Donut({ slices, size, thickness, hues, children, label, className }: DonutProps): react.JSX.Element;
 
 interface SparklineProps {
@@ -305,7 +153,7 @@ interface SparklineProps {
     label: string;
     className?: string;
 }
-/** Trend at a glance. No axis, no scale, so it is a Widget rather than a Chart (ADR 0007). */
+/** Trend at a glance. No axis, no scale, so it is a Widget rather than a Chart. */
 declare function Sparkline({ values, width, height, tone, hue, filled, showLast, label, className, }: SparklineProps): react.JSX.Element;
 interface BarMiniProps {
     values: number[];
@@ -361,108 +209,6 @@ interface LeaderboardProps {
  * 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 Breadcrumb({ 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 Steps({ 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 Statistic({ label, value, delta, caption, hue, icon, visual, className }: StatCardProps): react.JSX.Element;
-declare namespace Statistic {
-    var Skeleton: typeof StatCardSkeleton;
-}
-interface StatCardSkeletonProps {
-    withVisual?: boolean;
-    className?: string;
-}
-/** Built from Statistic's own spacing, so the tile does not resize when data arrives (ADR 0009). */
-declare function StatCardSkeleton({ withVisual, className }: StatCardSkeletonProps): react.JSX.Element;
+declare const Leaderboard: typeof LeaderboardRoot;
 
-export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, Badge, type BadgeProps, BarMini, type BarMiniProps, Breadcrumb, type BreadcrumbsProps, Container, type ContainerProps, type Crumb, type DecorHue, Divider, type DividerProps, Donut, type DonutArc, type DonutProps, type DonutSlice, Empty, type EmptyStateProps, Flex, type GlassStyle, Grid, type GridProps, Heading, type HeadingProps, Leaderboard, type LeaderboardEntry, type LeaderboardProps, type LeaderboardSkeletonProps, LinkButton, type LinkButtonProps, ProgressBar, type ProgressBarProps, ProgressRing, type ProgressRingProps, type RingGeometry, type Size, Skeleton, type SkeletonProps, type SkeletonTextProps, Sparkline, type SparklineGeometry, type SparklineProps, Spin, type SpinnerProps, type StackProps, type StatCardProps, type StatCardSkeletonProps, Statistic, type Step, type StepperProps, Steps, Surface, type SurfaceProps, type SurfaceVariant, Text, type TextProps, Timeline, type TimelineEntry, type TimelineProps, type TimelineSkeletonProps, type Tone, cn, donutArcs, hueForName, initialsOf, ringGeometry, sparklineGeometry };
+export { BarMini, type BarMiniProps, Container, type ContainerProps, type DecorHue, Donut, type DonutArc, type DonutProps, type DonutSlice, Flex, type GlassStyle, Grid, type GridProps, Heading, type HeadingProps, Leaderboard, type LeaderboardEntry, type LeaderboardProps, PageContainer, type PageContainerProps, PageContainerSkeleton, type PageContainerSkeletonProps, type Size, Sparkline, type SparklineGeometry, type SparklineProps, type StackProps, Surface, type SurfaceProps, type SurfaceVariant, Text, type TextProps, type Tone, cn, donutArcs, sparklineGeometry };