@iamfiro/design 0.0.0-stage → 0.1.0

package/lib/types/components/Alert/Alert.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+import './Alert.css';
+export type AlertTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+export interface AlertProps {
+    tone?: AlertTone;
+    title?: ReactNode;
+    /** Body text. */
+    children?: ReactNode;
+    /** Custom icon, or false to hide it. */
+    icon?: ReactNode | false;
+    /** Buttons under the text (or on the right for `layout="inline"`). */
+    actions?: ReactNode;
+    /** Shows a × that folds the alert away, then calls this. */
+    onClose?: () => void;
+    /** stacked: actions under the text · inline: one row, actions on the right. */
+    layout?: 'stacked' | 'inline';
+    className?: string;
+}
+/**
+ * A message that stays on the page (unlike a toast): form errors, limits, plan notices.
+ * Soft tinted background, no border; dismissing folds it away instead of popping out.
+ */
+export declare function Alert({ tone, title, children, icon, actions, onClose, layout, className }: AlertProps): import("react").JSX.Element;
+export interface BannerProps {
+    tone?: AlertTone;
+    children: ReactNode;
+    /** One action (a link-style button) after the message. */
+    action?: ReactNode;
+    onClose?: () => void;
+    icon?: ReactNode | false;
+    /** Square corners for a strip that spans the whole page or app edge to edge. */
+    flush?: boolean;
+    className?: string;
+}
+/** A full-width strip at the top of a page or app: maintenance, trial ending, new version. */
+export declare function Banner({ tone, children, action, onClose, icon, flush, className }: BannerProps): import("react").JSX.Element;

package/lib/types/components/AppShell/AppShell.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from 'react';
+import './AppShell.css';
+export interface AppShellProps {
+    /** Usually a <Sidebar>. */
+    sidebar: ReactNode;
+    /** A bar at the top of the main area (actions, search…). */
+    header?: ReactNode;
+    children: ReactNode;
+    /**
+     * plain: one white page, the window scrolls.
+     * inset: the sidebar sits on a gray canvas and the main area floats beside it as a white panel
+     * that scrolls on its own.
+     */
+    variant?: 'plain' | 'inset';
+    /** Width of the sidebar on wide screens. */
+    sidebarWidth?: number;
+    /** Wide screens: folds the sidebar away (it slides out while the main area widens). */
+    sidebarCollapsed?: boolean;
+    /** Narrow screens: the sidebar becomes a drawer that you open and close. */
+    mobileSidebarOpen?: boolean;
+    onMobileSidebarOpenChange?: (open: boolean) => void;
+    /** A panel on the right (details, tools, a workspace panel). Hidden on narrow screens (≤ 900px). */
+    aside?: ReactNode;
+    /** Width of the right panel, px. */
+    asideWidth?: number;
+    /** Shows or hides the right panel; it slides in and out while the main area resizes. */
+    asideOpen?: boolean;
+    /** Accessible name of the right panel. */
+    asideLabel?: string;
+    /** When this changes (a new page), the main area scrolls back to the top. */
+    scrollKey?: unknown;
+    className?: string;
+}
+/**
+ * Page frame: a fixed sidebar beside a scrolling main area (and an optional panel on the right);
+ * the sidebar becomes a slide-in drawer on small screens.
+ */
+export declare function AppShell({ sidebar, header, children, variant, sidebarWidth, sidebarCollapsed, mobileSidebarOpen, onMobileSidebarOpenChange, aside, asideWidth, asideOpen, asideLabel, scrollKey, className, }: AppShellProps): import("react").JSX.Element;

package/lib/types/components/AreaChart/AreaChart.d.ts

@@ -0,0 +1,17 @@
+import { type LineChartProps } from '../LineChart/LineChart';
+export type AreaChartType = 'default' | 'stacked' | 'percent';
+export interface AreaChartProps extends Omit<LineChartProps, 'area' | 'stack'> {
+    /**
+     * default: every series from the baseline, translucent and overlapping · stacked: layers piled on
+     * top of each other (the top edge is the total) · percent: every row scaled to 100% (shares).
+     */
+    type?: AreaChartType;
+    /** gradient: fades downward · solid: one flat soft tint. */
+    fill?: 'gradient' | 'solid';
+}
+/**
+ * Filled areas over the same axes, tooltip, legend and keyboard guide as LineChart — it is LineChart
+ * with `area` on plus the stacking modes, so bands, reference lines, end dots and streaming all work.
+ * Stacked tooltips list the top layer first and end with the row total.
+ */
+export declare function AreaChart({ type, fill, 'aria-label': ariaLabel, className, ...rest }: AreaChartProps): import("react").JSX.Element;

package/lib/types/components/BarChart/BarChart.d.ts

@@ -0,0 +1,57 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type ChartRow, type ChartSeries } from '../Chart/chart';
+import './BarChart.css';
+export type BarSeries = ChartSeries;
+export type BarChartRow = ChartRow;
+export interface BarChartProps {
+    data: BarChartRow[];
+    /** Field used for the x axis (a label per row). */
+    xKey: string;
+    series: BarSeries[];
+    /** Plot height in px (axis labels included). */
+    height?: number;
+    /** Stack the series in one bar per row instead of side by side. */
+    stacked?: boolean;
+    /** White gap in px between stacked segments. */
+    segmentGap?: number;
+    /** Number of y-axis labels, 0 included. */
+    yTickCount?: number;
+    yMax?: number;
+    /** Exact y-axis values (e.g. `[0, 50, 100]`); overrides `yTickCount` and `yMax`. */
+    yTicks?: number[];
+    /** Side of the value axis. */
+    yAxis?: 'left' | 'right';
+    formatValue?: (value: number, series: BarSeries) => string;
+    formatAxisValue?: (value: number) => string;
+    formatX?: (row: BarChartRow, index: number) => string;
+    formatTitle?: (row: BarChartRow, index: number) => ReactNode;
+    /** Icon under each bar instead of a text label; the selected one opens into a chip with icon + label. */
+    xIcon?: (row: BarChartRow, index: number) => ReactNode;
+    /** Footer row with the sum (stacked bars show it by default). */
+    showTotal?: boolean;
+    /** Where the sum goes: a footer row, or on the right of the tooltip title. */
+    totalPlacement?: 'footer' | 'header';
+    /** Node before the tooltip title (a Checkbox, an icon). */
+    tooltipLeading?: (row: BarChartRow, index: number) => ReactNode;
+    /** Tooltip row order: `series` order, `reverse` (top of the stack first) or biggest value first. */
+    tooltipSort?: 'series' | 'reverse' | 'value';
+    legend?: boolean;
+    activeIndex?: number | null;
+    defaultActiveIndex?: number | null;
+    onActiveIndexChange?: (index: number | null) => void;
+    /** Rows can be picked by click, Enter or Space. Implied by `selected` · `defaultSelected` · `onSelectedChange`. */
+    selectable?: boolean;
+    /** Picked row (controlled). The other rows are drawn in faded tints. */
+    selected?: number | null;
+    defaultSelected?: number | null;
+    onSelectedChange?: (index: number | null) => void;
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Grouped or stacked bars over the same axes as LineChart. Hovering a row fills its band with the
+ * small gray and the value card sits beside it; bars grow from the baseline and morph on new data.
+ * Selectable charts keep one row in full colour and fade the rest.
+ */
+export declare function BarChart({ data, xKey, series, height, stacked, segmentGap, yTickCount, yMax, yTicks, yAxis, formatValue, formatAxisValue, formatX, formatTitle, xIcon, showTotal, totalPlacement, tooltipLeading, tooltipSort, legend, activeIndex, defaultActiveIndex, onActiveIndexChange, selectable: selectableProp, selected: selectedProp, defaultSelected, onSelectedChange, 'aria-label': ariaLabel, className, style, }: BarChartProps): import("react").JSX.Element;

package/lib/types/components/BarList/BarList.d.ts

@@ -0,0 +1,56 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import './BarList.css';
+export interface BarListItem {
+    /** Stable id. Defaults to `name`. */
+    key?: string;
+    name: string;
+    value: number;
+    /** Small icon or IconTile before the name. */
+    icon?: ReactNode;
+    /** Turns the name into a link (ignored on clickable rows, which are buttons already). */
+    href?: string;
+    /** Bar color for this row only: a CSS variable (`--chart-2`) or any color, drawn as a soft tint. */
+    color?: string;
+}
+export type BarListTone = 'accent' | 'neutral' | 'success' | 'warning' | 'danger';
+export type BarListSortOrder = 'descending' | 'ascending' | 'none';
+export type BarListSize = 'sm' | 'md' | 'lg';
+export interface BarListProps {
+    data: BarListItem[];
+    /** Row order. `none` keeps the order of `data`. */
+    sortOrder?: BarListSortOrder;
+    /** Soft fill of the bars. */
+    tone?: BarListTone;
+    /** Bar color instead of `tone`: a CSS variable (`--chart-1`) or any color, drawn as a soft tint. */
+    color?: string;
+    formatValue?: (value: number, item: BarListItem) => string;
+    /** Rows become buttons (hover fill, Tab / ↑ ↓ focus); called with the picked row. */
+    onValueChange?: (item: BarListItem, index: number) => void;
+    /** Bars grow in on mount, slide to new widths and rows slide to new places when data changes. */
+    showAnimation?: boolean;
+    /** Value of a full-width bar. Defaults to the largest value. */
+    max?: number;
+    /** Rows shown before the "더 보기" button. */
+    limit?: number;
+    /** Rows past `limit` are shown (controlled). */
+    expanded?: boolean;
+    defaultExpanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    moreLabel?: (hidden: number) => ReactNode;
+    lessLabel?: ReactNode;
+    /** Overline header on the left ("페이지"). A header row shows when this or `valueLabel` is set. */
+    nameLabel?: ReactNode;
+    /** Overline header on the right ("방문수"). */
+    valueLabel?: ReactNode;
+    /** Row height: 28 · 32 · 36 px. */
+    size?: BarListSize;
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A ranked list of horizontal bars (top pages, sources, countries). Each bar is a soft tint as
+ * wide as its share of the largest value, drawn behind the name; the value sits right-aligned
+ * in tabular figures. Long lists fold behind "더 보기".
+ */
+export declare function BarList({ data, sortOrder, tone, color, formatValue, onValueChange, showAnimation, max, limit, expanded: expandedProp, defaultExpanded, onExpandedChange, moreLabel, lessLabel, nameLabel, valueLabel, size, 'aria-label': ariaLabel, className, style, }: BarListProps): import("react").JSX.Element;

package/lib/types/components/Breadcrumb/Breadcrumb.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import './Breadcrumb.css';
+export interface BreadcrumbItem {
+    label: ReactNode;
+    href?: string;
+    onClick?: () => void;
+}
+export interface BreadcrumbProps {
+    /** The last item is the current page. */
+    items: BreadcrumbItem[];
+    separator?: ReactNode;
+    className?: string;
+}
+/** Where this page sits; every item but the last links back up. */
+export declare function Breadcrumb({ items, separator, className }: BreadcrumbProps): import("react").JSX.Element;

package/lib/types/components/Calendar/Calendar.d.ts

@@ -0,0 +1,34 @@
+import './Calendar.css';
+import type { DateRange } from './date';
+export type { DateRange } from './date';
+interface CalendarBaseProps {
+    /** Earliest / latest pickable day. */
+    min?: Date;
+    max?: Date;
+    /** Extra rule for unpickable days (holidays, weekends…). */
+    isDateDisabled?: (date: Date) => boolean;
+    /** 0 = Sunday (default, as in Korean calendars), 1 = Monday. */
+    weekStartsOn?: 0 | 1;
+    /** The month shown first; defaults to the selected day's month, else today. */
+    defaultMonth?: Date;
+    /** Focus the selected (or today's) day when it mounts — for popovers. */
+    autoFocus?: boolean;
+    /** The bottom row with a "오늘" button (and, for ranges, what to pick next). */
+    showFooter?: boolean;
+    className?: string;
+}
+export type CalendarProps = CalendarBaseProps & ({
+    mode?: 'single';
+    value?: Date | null;
+    onValueChange?: (date: Date) => void;
+} | {
+    mode: 'range';
+    value?: DateRange;
+    onValueChange?: (range: DateRange) => void;
+});
+/**
+ * A month grid. Arrows move by day, PageUp/PageDown by month, Home/End to the week's ends,
+ * Enter/Space picks. Changing month slides the grid in from the direction you went.
+ * The header opens a year / month picker on one screen: scroll the years, tap a month, done.
+ */
+export declare function Calendar(props: CalendarProps): import("react").JSX.Element;

package/lib/types/components/Calendar/DatePicker.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from 'react';
+import { type DatePreset, type DateRange } from './date';
+import '../Select/Select.css';
+import './DatePicker.css';
+interface PickerBaseProps {
+    placeholder?: ReactNode;
+    size?: 'sm' | 'md' | 'lg';
+    disabled?: boolean;
+    invalid?: boolean;
+    /** Show an × to clear the value. */
+    clearable?: boolean;
+    min?: Date;
+    max?: Date;
+    isDateDisabled?: (date: Date) => boolean;
+    weekStartsOn?: 0 | 1;
+    /** Popover alignment to the field. */
+    align?: 'start' | 'end';
+    id?: string;
+    className?: string;
+    'aria-label'?: string;
+}
+export interface DatePickerProps extends Omit<PickerBaseProps, 'placeholder'> {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onValueChange?: (date: Date | null) => void;
+    /** How the picked date is written in the field when it isn't being edited. */
+    formatValue?: (date: Date) => string;
+    placeholder?: string;
+}
+/**
+ * A date field you can type into ("10/25", "2026.10.25", "내일"…) or pick from the Calendar.
+ * Typing a full date moves the calendar along; Enter confirms, ↓ jumps into the calendar,
+ * Esc closes or undoes the edit. Something unreadable shows as an error and reverts on leave.
+ */
+export declare function DatePicker({ value: valueProp, defaultValue, onValueChange, formatValue, placeholder, clearable, align, min, max, isDateDisabled, weekStartsOn, id, size, disabled, invalid, className, 'aria-label': ariaLabel, }: DatePickerProps): import("react").JSX.Element;
+export interface DateRangePickerProps extends PickerBaseProps {
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onValueChange?: (range: DateRange) => void;
+    /** Quick picks on the left; pass [] to hide. */
+    presets?: DatePreset[];
+}
+/** Start and end in one field. Pick two days (the band previews on hover) or a preset. */
+export declare function DateRangePicker({ value: valueProp, defaultValue, onValueChange, presets, placeholder, clearable, align, min, max, isDateDisabled, weekStartsOn, ...field }: DateRangePickerProps): import("react").JSX.Element;
+export {};

package/lib/types/components/Calendar/date.d.ts

@@ -0,0 +1,32 @@
+/** Small date helpers (local time, day precision). No library needed for a month view. */
+export declare const startOfDay: (d: Date) => Date;
+export declare const startOfMonth: (d: Date) => Date;
+export declare const addDays: (d: Date, n: number) => Date;
+export declare const addMonths: (d: Date, n: number) => Date;
+export declare const sameDay: (a: Date | null | undefined, b: Date | null | undefined) => boolean;
+export declare const sameMonth: (a: Date, b: Date) => boolean;
+export declare const compareDay: (a: Date, b: Date) => number;
+export declare const between: (d: Date, from: Date, to: Date) => boolean;
+/** The 6×7 days shown for a month, starting on `weekStartsOn` (0 = Sunday). */
+export declare function monthGrid(month: Date, weekStartsOn: number): Date[];
+export declare const weekdayLabels: (weekStartsOn: number) => string[];
+export declare const formatMonth: (d: Date) => string;
+/** "2026년 10월 25일" — the year is dropped when it's this year. */
+export declare const formatDate: (d: Date, withYear?: boolean) => string;
+export declare const formatFullDate: (d: Date) => string;
+export interface DateRange {
+    from: Date | null;
+    to: Date | null;
+}
+export interface DatePreset {
+    label: string;
+    /** Returns the range for this preset (computed when clicked, so "오늘" stays current). */
+    range: () => DateRange;
+}
+export declare const DEFAULT_DATE_PRESETS: DatePreset[];
+/**
+ * Reads what people actually type for a date:
+ * "2026-10-25", "2026.10.25.", "2026/10/25", "20261025", "10/25", "10.25", "10월 25일",
+ * "2026년 10월 25일", "25일", and 그제 / 어제 / 오늘 / 내일 / 모레. Returns null when it isn't a real date.
+ */
+export declare function parseDateInput(text: string, base?: Date): Date | null;

package/lib/types/components/Card/Card.d.ts

@@ -0,0 +1,64 @@
+import type { ComponentPropsWithRef, CSSProperties, ElementType, ReactNode } from 'react';
+import './Card.css';
+export type CardVariant = 'default' | 'raised' | 'plain';
+export type CardPadding = 'none' | 'sm' | 'md' | 'lg';
+interface CardOwnProps<E extends ElementType> {
+    /** Render as a link or button for clickable cards (`interactive` adds hover/press feedback). */
+    as?: E;
+    /** default: faint outline + soft lift · raised: floats higher · plain: no shadow, grouped by spacing. */
+    variant?: CardVariant;
+    /** Inner padding for the parts inside (Header / Body / Footer read it). */
+    padding?: CardPadding;
+    interactive?: boolean;
+    /** Selectable card (radio / checkbox cards). Passing false still shows the empty check. */
+    selected?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+export type CardProps<E extends ElementType = 'div'> = CardOwnProps<E> & Omit<ComponentPropsWithRef<E>, keyof CardOwnProps<E>>;
+/** A white surface that groups related content. Compose with Card.Header / Body / Footer / Media. */
+export declare function Card<E extends ElementType = 'div'>({ as, variant, padding, interactive, selected, className, children, ...rest }: CardProps<E>): import("react").JSX.Element;
+export declare namespace Card {
+    var Header: typeof CardHeader;
+    var Body: typeof CardBody;
+    var Footer: typeof CardFooter;
+    var Media: typeof CardMedia;
+}
+export interface CardHeaderProps {
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Small text above the title (category, date…). */
+    eyebrow?: ReactNode;
+    /** Leading icon or avatar. */
+    icon?: ReactNode;
+    /** Trailing buttons, badge or menu. */
+    actions?: ReactNode;
+    /** Custom content instead of title/description. */
+    children?: ReactNode;
+    className?: string;
+}
+export declare function CardHeader({ title, description, eyebrow, icon, actions, children, className }: CardHeaderProps): import("react").JSX.Element;
+export declare function CardBody({ children, className, style }: {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+export interface CardFooterProps {
+    children?: ReactNode;
+    /** Where the footer content sits; `between` spreads two groups apart. */
+    align?: 'start' | 'end' | 'between';
+    /** A hairline above the footer (for dense cards with lots of body content). */
+    divided?: boolean;
+    /** A soft gray band across the bottom edge (status line + elapsed time) instead of plain padding. */
+    band?: boolean;
+    className?: string;
+}
+export declare function CardFooter({ children, align, divided, band, className }: CardFooterProps): import("react").JSX.Element;
+/** Full-bleed image / preview at the top or bottom edge of the card. */
+export declare function CardMedia({ children, ratio, className }: {
+    children: ReactNode;
+    ratio?: number | string;
+    className?: string;
+}): import("react").JSX.Element;
+export {};

package/lib/types/components/CardFrame/CardFrame.d.ts

@@ -0,0 +1,15 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import './CardFrame.css';
+export interface CardFrameProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** A caption line above the card, on the gray ("4단계 · gmail.send"). Two children spread to both ends. */
+    header?: ReactNode;
+    /** A status line below the card, on the gray ("실행 중 · 3/5" + elapsed). Two children spread to both ends. */
+    footer?: ReactNode;
+    /** Usually one `Card`. The frame leaves a 4px gray rim so the card's corners stay concentric. */
+    children?: ReactNode;
+}
+/**
+ * A soft gray tray that wraps a white card, with an optional caption above or status line below.
+ * The card stays the content; the tray carries context (which step, how far along) outside it.
+ */
+export declare function CardFrame({ header, footer, children, className, ...rest }: CardFrameProps): import("react").JSX.Element;

package/lib/types/components/Chart/ChartParts.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import './Chart.css';
+export interface ChartTooltipRow {
+    key: string;
+    label: ReactNode;
+    color: string;
+    value: ReactNode;
+}
+export interface ChartTooltipProps {
+    title?: ReactNode;
+    /** Node before the title (a Checkbox, an icon). */
+    leading?: ReactNode;
+    /** Value on the right of the title row (the category total). */
+    value?: ReactNode;
+    rows: ChartTooltipRow[];
+    footer?: ChartTooltipRow;
+}
+/** The floating value card: a raised Card with a title row, a hairline and ColorDot rows. */
+export declare function ChartTooltip({ title, leading, value, rows, footer }: ChartTooltipProps): import("react").JSX.Element;
+export interface ChartLegendItem {
+    key: string;
+    label: ReactNode;
+    color: string;
+    /** Shown on the right in the `list` layout. */
+    value?: ReactNode;
+    /** A muted second value after `value` in the `list` layout (share, unit). Kept in its own aligned column. */
+    detail?: ReactNode;
+}
+export interface ChartLegendProps {
+    items: ChartLegendItem[];
+    /** inline: one wrapping row under the plot · list: a column with values, beside a pie. */
+    layout?: 'inline' | 'list';
+    /** Key being highlighted; the others fade. */
+    focused?: string | null;
+    onFocusChange?: (key: string | null) => void;
+}
+/** Color keys for a chart. Hovering an entry highlights its series. */
+export declare function ChartLegend({ items, layout, focused, onFocusChange }: ChartLegendProps): import("react").JSX.Element;

package/lib/types/components/Chart/chart.d.ts

@@ -0,0 +1,46 @@
+export interface ChartSeries {
+    /** Field of each row that holds this series' number. */
+    key: string;
+    label: string;
+    /** CSS variable (`--chart-1`) or any color. Defaults to the chart palette in order. */
+    color?: string;
+}
+export type ChartRow = Record<string, string | number | null | undefined>;
+export declare const formatNumber: (v: number) => string;
+export declare const formatCompact: (v: number) => string;
+export declare const formatPercent: (ratio: number) => string;
+/** `--chart-1` … `--chart-6` in order unless the item names its own color. */
+export declare const chartColor: (color: string | undefined, index: number) => string;
+export declare const numberAt: (row: ChartRow | undefined, key: string) => number | null;
+/** 0 … top in `count - 1` equal, round steps (1 · 1.5 · 2 · 2.5 · 3 · 5 × 10ⁿ). */
+export declare function niceTicks(max: number, count: number): number[];
+/** Left gutter wide enough for the longest y label (rough glyph width of the caption role). */
+export declare const axisGutter: (labels: string[]) => number;
+/** Show every `step`-th x label so they keep at least `minGap` px apart. */
+export declare const labelStep: (count: number, span: number, minGap?: number) => number;
+type Point = [number, number];
+/** SVG paths through the points, one per unbroken run (`null` gaps split the line). */
+export declare function lineRuns(points: Array<Point | null>, curve: 'linear' | 'smooth'): {
+    d: string;
+    x0: number;
+    x1: number;
+}[];
+/** A rect with only the top corners rounded (bars grow from the baseline). */
+export declare function barPath(x: number, y: number, w: number, h: number, r: number): string;
+/** Annular sector from angle a0 to a1 (radians, 0 = 12 o'clock, clockwise). */
+export declare function arcPath(cx: number, cy: number, r: number, inner: number, a0: number, a1: number): string;
+/** Tone of an annotation (band, reference line). */
+export type ChartTone = 'neutral' | 'accent' | 'warning' | 'danger';
+/** Soft fill per tone, for bands behind the plot. */
+export declare const CHART_TONE_SOFT: Record<ChartTone, string>;
+/** Strong color per tone, for reference lines and their labels. */
+export declare const CHART_TONE_STRONG: Record<ChartTone, string>;
+/** One unbroken SVG path through the points (`linear` segments or the monotone `smooth` curve). */
+export declare const linePath: (points: Array<[number, number]>, curve: "linear" | "smooth") => string;
+/**
+ * A closed band between two edges over the same x positions: an area down to the baseline, or one
+ * layer of a stack. Both edges use the same commands, so a band morphs smoothly (CSS `d`) between
+ * overlapping and stacked shapes.
+ */
+export declare function bandPath(upper: Array<[number, number]>, lower: Array<[number, number]>, curve: 'linear' | 'smooth'): string;
+export {};

package/lib/types/components/Chart/useChartInteraction.d.ts

@@ -0,0 +1,39 @@
+import { type FocusEvent, type KeyboardEvent } from 'react';
+export interface ChartInteractionOptions {
+    /** Number of things the guide can land on (rows, bands, slices). */
+    count: number;
+    activeIndex?: number | null;
+    defaultActiveIndex?: number | null;
+    onActiveIndexChange?: (index: number | null) => void;
+    /** Keyboard focus lands here first. Defaults to the last item (the latest value). */
+    initialKeyboardIndex?: 'first' | 'last';
+}
+/**
+ * Hover · touch · keyboard highlighting shared by every chart.
+ * - `active` is the highlighted item (controllable); `shown` keeps the last one while things fade out.
+ * - Leaving the plot waits `TIMING.hoverGrace` so grazing the edge doesn't flicker.
+ * - `settled` turns on a frame after opening, so the tooltip appears in place and only slides afterwards.
+ */
+export declare function useChartInteraction({ count, activeIndex, defaultActiveIndex, onActiveIndexChange, initialKeyboardIndex }: ChartInteractionOptions): {
+    active: number | null;
+    setActive: (next: number | null) => void;
+    open: boolean;
+    shown: number | null;
+    settled: boolean;
+    width: number;
+    tipRef: import("react").RefObject<HTMLDivElement | null>;
+    tipSize: {
+        w: number;
+        h: number;
+    };
+    hover: (i: number | null) => void;
+    leave: () => void;
+    plotProps: {
+        ref: import("react").RefObject<HTMLDivElement | null>;
+        tabIndex: number;
+        role: "group";
+        onKeyDown: (e: KeyboardEvent<HTMLElement>) => void;
+        onFocus: (e: FocusEvent<HTMLElement>) => void;
+        onBlur: () => void;
+    };
+};

package/lib/types/components/ChatBubble/ChatBubble.d.ts

@@ -0,0 +1,61 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type DateInput } from '../../primitives';
+import './ChatBubble.css';
+/** `start` = someone else's message (left), `end` = mine (right). */
+export type ChatBubbleSide = 'start' | 'end';
+/** Fill: gray for the other side, blue or near-black for mine. */
+export type ChatBubbleTone = 'neutral' | 'accent' | 'primary';
+/** Where a bubble sits in one person's run; the corners facing its neighbours tighten. */
+export type ChatBubblePosition = 'single' | 'first' | 'middle' | 'last';
+/** Delivery state of a message I sent. `sending` is pending, `sent` / `read` are committed. */
+export type ChatBubbleStatus = 'sending' | 'sent' | 'read' | 'failed';
+export interface ChatBubbleProps {
+    /** Defaults to the enclosing `ChatBubbleGroup`'s side, else `start`. */
+    side?: ChatBubbleSide;
+    /** Defaults to `neutral` on the start side and `accent` on the end side. */
+    tone?: ChatBubbleTone;
+    /** Set by `ChatBubbleGroup`; pass it yourself only for a bubble outside a group. */
+    position?: ChatBubblePosition;
+    /** The message. */
+    children?: ReactNode;
+    /** When it was sent; shown as clock time beside the last bubble of a run, full date on hover. */
+    time?: DateInput;
+    /** Delivery state, beside the time. `failed` also shows a retry button when `onRetry` is given. */
+    status?: ChatBubbleStatus;
+    onRetry?: () => void;
+    /** Three bouncing dots instead of text: the other person is typing. */
+    typing?: boolean;
+    /** Buttons beside the bubble (react, reply, more). They appear while it's hovered or focused. */
+    actions?: ReactNode;
+    /** Under the bubble: reactions, an attachment, a link preview. */
+    footer?: ReactNode;
+    /** Rise in from below when it mounts — for a message that just arrived. */
+    appear?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** One chat message in a filled bubble. Group a person's run with `ChatBubbleGroup`. */
+export declare function ChatBubble({ side: sideProp, tone: toneProp, position: positionProp, children, time, status, onRetry, typing, actions, footer, appear, className, style, }: ChatBubbleProps): import("react").JSX.Element;
+export declare namespace ChatBubble {
+    var Group: typeof ChatBubbleGroup;
+}
+export interface ChatBubbleGroupProps {
+    /** Whose run this is. A string on the start side also draws an avatar and the name. */
+    author?: ReactNode;
+    /** Replaces the default avatar. Pass `null` to keep the gutter empty. */
+    avatar?: ReactNode;
+    side?: ChatBubbleSide;
+    /** Avatar size in px; the bubbles line up beside it. */
+    avatarSize?: number;
+    /** Name above the first bubble. On by default for the start side (group chats), off for 1:1. */
+    showName?: boolean;
+    /** `ChatBubble`s, oldest first. */
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * One person's run of messages: their bubbles stacked close together with the corners between
+ * them tightened, the avatar beside the last one and the name above the first.
+ */
+export declare function ChatBubbleGroup({ author, avatar, side, avatarSize, showName, children, className, style, }: ChatBubbleGroupProps): import("react").JSX.Element;

package/lib/types/components/ChatBubble/formatChatTime.d.ts

@@ -0,0 +1,2 @@
+/** "오후 3:12" — chat bubbles show the clock time, not "2분 전". */
+export declare function formatChatTime(date: Date): string;