@lar-works/design-system 0.0.0-stage → 0.1.1

package/src/display/TimeSeriesChart.tsx

@@ -0,0 +1,191 @@
+import { type PointerEvent, useState } from 'react';
+
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+
+export interface TimeSeriesPoint {
+    timestamp: number;
+    lar: number | null;
+    host: number | null;
+}
+
+export function TimeSeriesChartSkeleton() {
+    return (
+        <figure className="border-base-300 bg-base-100 min-w-0 rounded-lg border p-4">
+            <div className="mb-3 h-5">
+                <SkeletonLoader.Shape width="short" />
+            </div>
+            <SkeletonLoader.Shape presentation="chart" />
+            <div className="mt-3 flex h-4 items-center gap-5">
+                <SkeletonLoader.Shape width="short" />
+                <SkeletonLoader.Shape width="short" />
+            </div>
+            <div className="mt-1 flex h-4 items-center justify-between">
+                <SkeletonLoader.Shape width="short" />
+                <SkeletonLoader.Shape width="short" />
+            </div>
+        </figure>
+    );
+}
+
+type Series = 'host' | 'lar';
+
+interface TimeSeriesChartProps {
+    label: string;
+    larLabel: string;
+    hostLabel: string;
+    points: readonly TimeSeriesPoint[];
+    formatValue: (value: number) => string;
+    maximum?: number;
+    unavailableLabel: string;
+}
+
+const colors: Record<Series, string> = { host: 'var(--color-base-600)', lar: 'var(--color-primary)' };
+const time = (timestamp: number) => new Date(timestamp).toLocaleTimeString();
+
+/** Host and lar series, each drawn only when the server measured it, with gaps for missed samples. */
+export function TimeSeriesChart({
+    label,
+    larLabel,
+    hostLabel,
+    points,
+    formatValue,
+    maximum,
+    unavailableLabel,
+}: TimeSeriesChartProps) {
+    const [hovered, setHovered] = useState<number | null>(null);
+    const labels: Record<Series, string> = { host: hostLabel, lar: larLabel };
+    const series = (['host', 'lar'] as const).filter((kind) => points.some((point) => point[kind] !== null));
+
+    if (series.length === 0) return null;
+
+    const observed = points.flatMap((point) => series.map((kind) => point[kind])).filter((value) => value !== null);
+    const upper = Math.max(maximum ?? 0, ...observed, 1);
+    const latest = points.at(-1);
+    const first = points[0]?.timestamp ?? 0;
+    const last = latest?.timestamp ?? first;
+    const span = Math.max(last - first, 1);
+    // Plot coordinates in percent of the viewBox, shared by the SVG lines and the HTML hover layer.
+    const x = (timestamp: number) => 2 + ((timestamp - first) / span) * 96;
+    const y = (value: number) => 38 - (Math.max(0, value) / upper) * 36;
+    const path = (kind: Series) =>
+        points
+            .map((point, index) => {
+                const value = point[kind];
+
+                if (value === null) return '';
+
+                // A sample after a gap starts a segment; a zero-length one draws as a dot through the round cap.
+                const start = points[index - 1]?.[kind] == null;
+
+                return `${start ? 'M' : 'L'}${x(point.timestamp).toFixed(2)},${y(value).toFixed(2)}${start ? 'h0' : ''}`;
+            })
+            .join(' ');
+    const latestText = (kind: Series) => (latest?.[kind] == null ? unavailableLabel : formatValue(latest[kind]));
+    const swatch = (kind: Series) => (
+        <span aria-hidden="true" className="size-2 shrink-0 rounded-full" style={{ backgroundColor: colors[kind] }} />
+    );
+    const active = hovered === null ? undefined : points[hovered];
+    const readings = active
+        ? series.flatMap((kind) => {
+              const value = active[kind];
+
+              return value === null ? [] : [{ kind, value }];
+          })
+        : [];
+    const trackPointer = (event: PointerEvent<HTMLDivElement>) => {
+        const bounds = event.currentTarget.getBoundingClientRect();
+        const target = ((event.clientX - bounds.left) / bounds.width) * 100;
+        const distance = (point: TimeSeriesPoint) => Math.abs(x(point.timestamp) - target);
+
+        setHovered(
+            points.reduce(
+                (best, point, index) => (distance(point) < distance(points[best] ?? point) ? index : best),
+                0,
+            ),
+        );
+    };
+
+    return (
+        <figure className="border-base-300 bg-base-100 min-w-0 rounded-lg border p-4">
+            <figcaption className="text-base-content mb-3 text-sm font-medium">{label}</figcaption>
+            <div
+                className="relative h-36 w-full touch-pan-y"
+                onPointerMove={trackPointer}
+                onPointerLeave={() => setHovered(null)}
+            >
+                <svg
+                    aria-label={`${label}: ${series.map((kind) => `${labels[kind]} ${latestText(kind)}`).join(', ')}`}
+                    className="size-full overflow-visible"
+                    preserveAspectRatio="none"
+                    role="img"
+                    viewBox="0 0 100 40"
+                >
+                    <path
+                        d="M2,38 H98 M2,20 H98 M2,2 H98"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeOpacity="0.12"
+                        strokeWidth="0.25"
+                    />
+                    {series.map((kind) => (
+                        <path
+                            key={kind}
+                            d={path(kind)}
+                            fill="none"
+                            stroke={colors[kind]}
+                            strokeLinecap="round"
+                            strokeWidth="2"
+                            vectorEffect="non-scaling-stroke"
+                        />
+                    ))}
+                </svg>
+                {active && readings.length > 0 ? (
+                    <div aria-hidden="true" className="pointer-events-none absolute inset-0">
+                        <div
+                            className="bg-base-content/20 absolute inset-y-0 w-px -translate-x-1/2"
+                            style={{ left: `${x(active.timestamp)}%` }}
+                        />
+                        {readings.map(({ kind, value }) => (
+                            <div
+                                key={kind}
+                                className="ring-base-50 absolute size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full ring-2"
+                                style={{
+                                    left: `${x(active.timestamp)}%`,
+                                    top: `${(y(value) / 40) * 100}%`,
+                                    backgroundColor: colors[kind],
+                                }}
+                            />
+                        ))}
+                        <div
+                            className={`border-base-300 bg-base-100 absolute top-0 z-10 w-max rounded-md border px-2 py-1 text-xs shadow-sm ${x(active.timestamp) > 50 ? '-ml-2 -translate-x-full' : 'ml-2'}`}
+                            style={{ left: `${x(active.timestamp)}%` }}
+                        >
+                            <div className="text-base-600 tabular-nums">{time(active.timestamp)}</div>
+                            {readings.map(({ kind, value }) => (
+                                <div key={kind} className="text-base-content flex items-center gap-1.5 tabular-nums">
+                                    {swatch(kind)}
+                                    {labels[kind]}: {formatValue(value)}
+                                </div>
+                            ))}
+                        </div>
+                    </div>
+                ) : null}
+            </div>
+            <div className="text-base-700 mt-3 flex flex-wrap items-center gap-x-5 gap-y-1 text-xs">
+                {series.map((kind) => (
+                    <span key={kind} className="inline-flex items-center gap-1.5">
+                        {swatch(kind)}
+                        {labels[kind]}: {latestText(kind)}
+                    </span>
+                ))}
+                <span className="ml-auto tabular-nums">{formatValue(upper)}</span>
+            </div>
+            {points.length > 1 ? (
+                <div className="text-base-600 mt-1 flex justify-between text-xs tabular-nums">
+                    <span>{time(first)}</span>
+                    <span>{time(last)}</span>
+                </div>
+            ) : null}
+        </figure>
+    );
+}

package/src/display/ToneTile.ts

@@ -0,0 +1,10 @@
+import type { StatusTone } from '../feedback/StatusIndicator';
+
+/** A small square holding an icon, tinted by tone: T3 Code's 8% tint behind its foreground colour. */
+export const toneTileClasses: Record<StatusTone, string> = {
+    neutral: 'bg-base-200 text-base-700 ring-1 ring-inset ring-base-300/70 dark:bg-base-300/60',
+    success: 'bg-success/10 text-(--lar-success-text) dark:bg-success/16',
+    warning: 'bg-warning/12 text-(--lar-warning-text) dark:bg-warning/16',
+    danger: 'bg-danger/10 text-(--lar-danger-text) dark:bg-danger/16',
+    info: 'bg-info/10 text-(--lar-info-text) dark:bg-info/16',
+};

package/src/display/index.ts

@@ -0,0 +1,37 @@
+export { ActivityCard, ActivityCardSkeleton } from './ActivityCard';
+export { Artwork } from './Artwork';
+export { Avatar } from './Avatar';
+export { Badge, type BadgeProps } from './Badge';
+export { BadgeList, type BadgeListItem } from './BadgeList';
+export { BrandLink, BrandMark } from './BrandMark';
+export { ChangeList, type ChangeListItem } from './ChangeList';
+export { CheckList, type CheckListItem } from './CheckList';
+export { CodeBlock } from './CodeBlock';
+export { CopyButton } from './CopyButton';
+export { DataTable, type DataTableCell, type DataTableRow } from './DataTable';
+export { DetailHero, DetailHeroDetail, DetailHeroDetails, DetailHeroTags } from './DetailHero';
+export { DetailList } from './DetailList';
+export { DeviceCard } from './DeviceCard';
+export { Identity } from './Identity';
+export { ImageCard } from './ImageCard';
+export { ImagePicker, ImagePickerGrid, ImagePickerOption, ImageUpload } from './ImagePicker';
+export { InfoBox } from './InfoBox';
+export { InsetPanel } from './InsetPanel';
+export { ItemAction } from './ItemAction';
+export { Kbd } from './Kbd';
+export { KindIcon } from './KindIcon';
+export { NoticeCard } from './NoticeCard';
+export { PairingList, type PairingListItem } from './PairingList';
+export { PathList } from './PathList';
+export { PeoplePreview } from './PeoplePreview';
+export { PropertySheet, type PropertySheetRow, type PropertySheetTag } from './PropertySheet';
+export { QrCode } from './QrCode';
+export { RadioChoice } from './RadioChoice';
+export { RatingLink } from './RatingLink';
+export { ResourceCard, ResourceCardSkeleton } from './ResourceCard';
+export { RowList, RowListItem } from './RowList';
+export { MeterLegend, type MeterSegment, type MeterTone, StackedMeter } from './StackedMeter';
+export { StatTile } from './StatTile';
+export { StepList } from './StepList';
+export { TextPreview } from './TextPreview';
+export { TimeSeriesChart, TimeSeriesChartSkeleton, type TimeSeriesPoint } from './TimeSeriesChart';

package/src/feedback/Alert.tsx

@@ -0,0 +1,35 @@
+import { Alert as NinnaAlert, type AlertProps as NinnaAlertProps } from '@ninna-ui/feedback';
+
+import type { StatusTone } from './StatusIndicator';
+
+type AlertProps = Omit<NinnaAlertProps, 'color' | 'size' | 'variant'> & {
+    compact?: boolean;
+    /** Stays below the application header while its containing region is visible. */
+    sticky?: boolean;
+    tone?: Exclude<StatusTone, 'neutral'>;
+};
+
+/**
+ * An immediate status about a condition or operation. Compact notes can hold short inline guidance.
+ * Use NoticeCard for content that needs examination and InfoBox for guidance that opens another surface.
+ */
+export function Alert({ compact = false, sticky = false, tone = 'info', className = '', ...props }: AlertProps) {
+    return (
+        <NinnaAlert
+            size={compact ? 'xs' : 'sm'}
+            showIcon
+            {...props}
+            color={tone}
+            className={
+                (sticky ? 'bg-base-50 sticky top-(--lar-header-height,0px) z-30 shadow-sm ' : '') +
+                (compact
+                    ? '[&_[data-slot=description]]:text-xs [&_[data-slot=icon]>svg]:size-4 [&_[data-slot=title]]:text-xs '
+                    : '') +
+                (tone === 'warning'
+                    ? '[&_[data-slot=description]]:text-(--lar-warning-text) [&_[data-slot=description]]:opacity-100 [&_[data-slot=title]]:text-(--lar-warning-text) '
+                    : '') +
+                className
+            }
+        />
+    );
+}

package/src/feedback/AsyncState.tsx

@@ -0,0 +1,56 @@
+import { Alert } from '@ninna-ui/feedback';
+import type { ReactNode } from 'react';
+
+import { Button } from '../actions/Button';
+import { SkeletonLoader } from './SkeletonLoader';
+
+interface AsyncStateProps {
+    placeholder?: ReactNode;
+    error?: string;
+    errorTitle: string;
+    label: string;
+    loading: boolean;
+    onRetry?: () => void;
+    presentation?: 'card' | 'line';
+    retryLabel?: string;
+    retrying?: boolean;
+}
+
+/** Owns a region's loading geometry and load failure; use Alert for other operation feedback. */
+export function AsyncState({
+    error,
+    errorTitle,
+    label,
+    loading,
+    onRetry,
+    presentation = 'card',
+    placeholder,
+    retryLabel,
+    retrying = false,
+}: AsyncStateProps) {
+    if (loading) {
+        return (
+            <SkeletonLoader label={label}>
+                {placeholder ?? <SkeletonLoader.Shape presentation={presentation} />}
+            </SkeletonLoader>
+        );
+    }
+
+    if (!error) return null;
+
+    return (
+        <Alert
+            color="danger"
+            title={errorTitle}
+            description={error}
+            showIcon
+            action={
+                onRetry && retryLabel ? (
+                    <Button type="button" onClick={onRetry} variant="primary" loading={retrying}>
+                        {retryLabel}
+                    </Button>
+                ) : undefined
+            }
+        />
+    );
+}

package/src/feedback/ErrorNotification.ts

@@ -0,0 +1,24 @@
+import { toast } from '@ninna-ui/feedback';
+
+export interface ErrorNotification {
+    description: string;
+    title: string;
+}
+
+export function dismissAllNotifications(): void {
+    toast.dismissAll();
+}
+
+export function showErrorNotification(notification: ErrorNotification): void {
+    toast.create({
+        ...notification,
+        color: 'danger',
+    });
+}
+
+export function showSuccessNotification(message: string): void {
+    toast.create({
+        color: 'success',
+        title: message,
+    });
+}

package/src/feedback/Notifications.tsx

@@ -0,0 +1,5 @@
+import { Toaster } from '@ninna-ui/feedback';
+
+export function Notifications() {
+    return <Toaster position="bottom-right" />;
+}

package/src/feedback/ProgressStatusRow.tsx

@@ -0,0 +1,104 @@
+import { ChevronRightIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { Button } from '../actions/Button';
+import { StatusIndicator, type StatusTone } from './StatusIndicator';
+
+interface ProgressStatusRowProps {
+    active: boolean;
+    detail?: string;
+    secondaryDetail?: string;
+    issue?: string;
+    label: string;
+    progress?: { max: number; value: number };
+    tone?: StatusTone;
+    trailing?: ReactNode;
+    onDetails?: () => void;
+    detailsLabel?: string;
+    progressLabel?: string;
+    compact?: boolean;
+}
+
+/** Ledger rows reserve the count line and track so updates never displace controls. */
+export function ProgressStatusRow({
+    active,
+    detail,
+    secondaryDetail,
+    issue,
+    label,
+    progress,
+    tone = 'info',
+    trailing,
+    onDetails,
+    detailsLabel,
+    progressLabel,
+    compact = false,
+}: ProgressStatusRowProps) {
+    const known = progress && progress.max > 0 ? progress : undefined;
+    const colors = {
+        info: 'bg-primary',
+        success: 'bg-success',
+        danger: 'bg-danger',
+        warning: 'bg-warning',
+        neutral: 'bg-base-400',
+    };
+    const heading = (
+        <>
+            <StatusIndicator tone={tone} />
+            <span className="text-base-content min-w-0 flex-1 truncate" title={label}>
+                {label}
+            </span>
+        </>
+    );
+
+    return (
+        <div className="w-full min-w-0">
+            <div className="grid min-h-12 min-w-0 grid-cols-[minmax(0,1fr)_auto] content-center items-center gap-x-3 gap-y-1">
+                {onDetails ? (
+                    <Button
+                        variant="status"
+                        className="w-full"
+                        onClick={onDetails}
+                        aria-label={detailsLabel}
+                        aria-haspopup="dialog"
+                    >
+                        {heading}
+                        <ChevronRightIcon />
+                    </Button>
+                ) : (
+                    <div className="flex h-4 min-w-0 items-center gap-1.5 text-xs">{heading}</div>
+                )}
+                {trailing ? <div className="col-start-2 row-span-3 row-start-1 shrink-0">{trailing}</div> : null}
+                <div
+                    className={`text-2xs text-base-700 col-start-1 tabular-nums ${compact ? 'truncate' : 'break-words'}`}
+                    title={detail}
+                >
+                    {detail || '\u00a0'}
+                </div>
+                <div
+                    className="bg-base-300/70 col-start-1 h-1.5 overflow-hidden rounded-full"
+                    role={active ? 'progressbar' : undefined}
+                    aria-label={active ? progressLabel || detail || label : undefined}
+                    aria-valuenow={active && known ? known.value : undefined}
+                    aria-valuemin={active && known ? 0 : undefined}
+                    aria-valuemax={active && known ? known.max : undefined}
+                >
+                    {active ? (
+                        <div
+                            className={`h-full rounded-full ${colors[tone]} ${known ? '' : 'lar-progress-indeterminate'}`}
+                            style={
+                                known
+                                    ? { width: `${Math.min(100, Math.max(0, (known.value / known.max) * 100))}%` }
+                                    : undefined
+                            }
+                        />
+                    ) : null}
+                </div>
+            </div>
+            {issue ? <div className="text-2xs break-words text-(--lar-danger-text) tabular-nums">{issue}</div> : null}
+            {secondaryDetail ? (
+                <div className="text-2xs text-base-700 break-words tabular-nums">{secondaryDetail}</div>
+            ) : null}
+        </div>
+    );
+}

package/src/feedback/SkeletonLoader.tsx

@@ -0,0 +1,88 @@
+/* oxlint-disable react/only-export-components -- Compound members are exported through SkeletonLoader. */
+
+import { Fragment, type ReactNode } from 'react';
+
+type SkeletonPresentation =
+    | 'artwork'
+    | 'poster'
+    | 'video'
+    | 'card'
+    | 'chart'
+    | 'circle'
+    | 'control'
+    | 'heading'
+    | 'line'
+    | 'metric';
+type SkeletonWidth = 'action' | 'full' | 'medium' | 'short' | 'wide';
+
+const presentationClasses: Record<SkeletonPresentation, string> = {
+    artwork: 'aspect-square',
+    poster: 'aspect-[2/3]',
+    video: 'aspect-video',
+    card: 'h-32',
+    chart: 'h-36',
+    circle: 'size-9',
+    control: 'h-10',
+    heading: 'h-[1cap]',
+    line: 'h-3.5',
+    metric: 'h-8',
+};
+
+const presentationRadius = {
+    artwork: 'rounded-lg',
+    poster: 'rounded-lg',
+    video: 'rounded-lg',
+    card: 'rounded-xl',
+    chart: 'rounded-md',
+    circle: 'rounded-full',
+    control: 'rounded-md',
+    heading: 'rounded-md',
+    line: 'rounded-full',
+    metric: 'rounded-md',
+} as const;
+
+const widthClasses: Record<SkeletonWidth, string> = {
+    action: 'w-20',
+    full: 'w-full',
+    medium: 'w-1/2',
+    short: 'w-1/3',
+    wide: 'w-3/4',
+};
+
+interface SkeletonLoaderProps {
+    children: ReactNode;
+    label: string;
+    loading?: boolean;
+}
+
+function SkeletonLoaderRoot({ children, label, loading = true }: SkeletonLoaderProps) {
+    if (!loading) return <Fragment>{children}</Fragment>;
+
+    return (
+        <div role="status" aria-busy="true" aria-label={label}>
+            <div aria-hidden="true">{children}</div>
+        </div>
+    );
+}
+
+interface SkeletonShapeProps {
+    presentation?: SkeletonPresentation;
+    width?: SkeletonWidth;
+}
+
+function SkeletonShape({ presentation = 'line', width = 'full' }: SkeletonShapeProps) {
+    const classes = [presentationClasses[presentation], presentation === 'circle' ? null : widthClasses[width]]
+        .filter(Boolean)
+        .join(' ');
+
+    return (
+        <span
+            aria-hidden="true"
+            role="presentation"
+            data-slot="skeleton"
+            className={`lar-skeleton block ${classes} ${presentationRadius[presentation]}`}
+        />
+    );
+}
+
+export const SkeletonLoader = Object.assign(SkeletonLoaderRoot, { Shape: SkeletonShape });

package/src/feedback/StatusIndicator.tsx

@@ -0,0 +1,28 @@
+export type StatusTone = 'neutral' | 'success' | 'warning' | 'danger' | 'info';
+
+interface StatusIndicatorProps {
+    className?: string;
+    size?: 'sm' | 'md';
+    tone: StatusTone;
+}
+
+const toneClasses: Record<StatusTone, string> = {
+    neutral: 'bg-base-400',
+    success: 'bg-success',
+    warning: 'bg-warning',
+    danger: 'bg-danger',
+    info: 'bg-info',
+};
+
+const sizeClasses: Record<NonNullable<StatusIndicatorProps['size']>, string> = {
+    sm: 'size-1.5',
+    md: 'size-2',
+};
+
+export function StatusIndicator({ className, size = 'md', tone }: StatusIndicatorProps) {
+    const classes = ['inline-block shrink-0 rounded-full', sizeClasses[size], toneClasses[tone], className]
+        .filter(Boolean)
+        .join(' ');
+
+    return <span aria-hidden="true" className={classes} />;
+}

package/src/feedback/StatusPopoverContent.tsx

@@ -0,0 +1,54 @@
+import { Box } from '@ninna-ui/layout';
+import { Popover } from '@ninna-ui/overlays';
+import type { ReactNode } from 'react';
+
+import { Badge } from '../display/Badge';
+import { Inline, Stack } from '../layout/Flow';
+import { Text } from '../typography/Typography';
+import { type StatusTone } from './StatusIndicator';
+
+interface StatusPopoverContentProps {
+    children: ReactNode;
+    detail?: string;
+    status: string;
+    title: string;
+    tone: StatusTone;
+    width?: 'sm' | 'md';
+}
+
+const widthClasses: Record<NonNullable<StatusPopoverContentProps['width']>, string> = {
+    sm: 'w-72',
+    md: 'w-80',
+};
+
+export function StatusPopoverContent({
+    children,
+    detail,
+    status,
+    title,
+    tone,
+    width = 'sm',
+}: StatusPopoverContentProps) {
+    return (
+        <Popover.Content side="bottom" align="end" sideOffset={8} className={`${widthClasses[width]} p-0`}>
+            <Box className="border-base-300 border-b p-4">
+                <Inline align="center" justify="between" space="group">
+                    <Stack space="none">
+                        <Text as="span" variant="label">
+                            {title}
+                        </Text>
+                        {detail ? (
+                            <Text as="span" variant="caption" tone="muted">
+                                {detail}
+                            </Text>
+                        ) : null}
+                    </Stack>
+                    <Badge tone={tone}>{status}</Badge>
+                </Inline>
+            </Box>
+            <Stack space="tight" className="p-2">
+                {children}
+            </Stack>
+        </Popover.Content>
+    );
+}