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

package/src/display/InsetPanel.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+
+import { tabbable } from '../foundations/KeyboardFocus';
+import { Stack } from '../layout/Flow';
+
+interface InsetPanelProps {
+    children: ReactNode;
+    onClick?: () => void;
+    presentation?: 'default' | 'settings';
+}
+
+/**
+ * A neutral surface that groups related content without adding message or status meaning.
+ * Use Alert for current status, InfoBox for optional guidance, and NoticeCard for a decision item.
+ */
+export function InsetPanel({ children, onClick, presentation = 'default' }: InsetPanelProps) {
+    if (presentation === 'settings') {
+        return (
+            <div className="divide-base-300 border-base-300 bg-base-100 divide-y overflow-hidden rounded-lg border shadow-xs/5">
+                {children}
+            </div>
+        );
+    }
+
+    return (
+        <Stack
+            as={onClick ? 'button' : 'div'}
+            type={onClick ? 'button' : undefined}
+            tabIndex={onClick ? tabbable.tabIndex : undefined}
+            onClick={onClick}
+            space="related"
+            className={`border-base-300 bg-base-100 rounded-lg border p-5 ${onClick ? 'focus-visible:outline-primary w-full cursor-pointer text-left focus-visible:outline-2 focus-visible:outline-offset-2' : ''}`}
+        >
+            {children}
+        </Stack>
+    );
+}

package/src/display/ItemAction.tsx

@@ -0,0 +1,53 @@
+import { Loading } from '@ninna-ui/feedback';
+import { PencilIcon } from 'lucide-react';
+
+export interface ItemActionProps {
+    label: string;
+    onClick?: () => void;
+}
+
+export function ItemAction({
+    action,
+    loading = false,
+    loadingLabel,
+}: {
+    action?: ItemActionProps;
+    loading?: boolean;
+    loadingLabel?: string;
+}) {
+    const disabled = loading || !action?.onClick;
+
+    if (!loading && !action) return null;
+
+    return (
+        <button
+            type="button"
+            aria-label={loading ? loadingLabel : action?.label}
+            aria-hidden={loading && !loadingLabel ? true : undefined}
+            aria-disabled={disabled}
+            tabIndex={disabled ? -1 : 0}
+            title={loading ? loadingLabel : action?.label}
+            className={`bg-base-50/90 text-base-content focus-visible:outline-primary pointer-events-auto flex size-6 items-center justify-center rounded-full shadow-sm backdrop-blur-sm transition-colors duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 motion-reduce:transition-none ${loading ? '' : 'opacity-0 group-hover/media-item:opacity-100 group-has-focus-visible/media-item:opacity-100 [@media(hover:none)]:opacity-100'} ${disabled ? 'cursor-default' : 'hover:bg-base-50 hover:text-primary cursor-pointer'}`}
+            onClick={(event) => {
+                event.stopPropagation();
+
+                if (!disabled) action?.onClick?.();
+            }}
+        >
+            {loading ? (
+                <Loading
+                    aria-hidden={!loadingLabel}
+                    className="motion-reduce:animate-none"
+                    color="primary"
+                    label={loadingLabel ?? ''}
+                    size="sm"
+                    variant="spin"
+                />
+            ) : (
+                <span className={`size-3.5 [&>svg]:size-full ${disabled ? 'opacity-40' : ''}`}>
+                    <PencilIcon />
+                </span>
+            )}
+        </button>
+    );
+}

package/src/display/Kbd.tsx

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+
+/** A keyboard key or shortcut, as quiet small text, such as ⌘K beside the search field. */
+export function Kbd({ children }: { children?: ReactNode }) {
+    return <kbd className="text-base-500 font-sans text-[11px] font-medium">{children}</kbd>;
+}

package/src/display/KindIcon.tsx

@@ -0,0 +1,15 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+/** Colours the icon inside it in a muted version of a lar-brand app hue, such as a catalog's kind; neutral without one. Its
+ *  container sizes the icon. */
+export function KindIcon({ hue, children }: { hue?: number; children: ReactNode }) {
+    return (
+        <span
+            aria-hidden="true"
+            className={`contents ${hue === undefined ? 'text-base-500 dark:text-base-600' : 'kind-icon'}`}
+            style={hue === undefined ? undefined : ({ '--lar-kind-hue': hue } as CSSProperties)}
+        >
+            {children}
+        </span>
+    );
+}

package/src/display/NoticeCard.tsx

@@ -0,0 +1,77 @@
+import { type ReactNode, useId } from 'react';
+
+import type { StatusTone } from '../feedback/StatusIndicator';
+import { Heading, Text } from '../typography/Typography';
+import { toneTileClasses } from './ToneTile';
+
+const accentClasses: Record<StatusTone, string> = {
+    neutral: 'border-l-base-300',
+    success: 'border-l-success',
+    warning: 'border-l-warning',
+    danger: 'border-l-danger',
+    info: 'border-l-info',
+};
+
+interface NoticeCardProps {
+    /** Buttons for what can be done, primary first. */
+    actions?: ReactNode;
+    /** A short status such as a severity, beside the title. */
+    badge?: ReactNode;
+    children?: ReactNode;
+    description: ReactNode;
+    /** Quiet content under the actions, such as a disclosure of technical details. */
+    footer?: ReactNode;
+    icon: ReactNode;
+    /** The title's heading level; one below the section the card sits in. */
+    level?: 'h2' | 'h3' | 'h4';
+    title: string;
+    tone: StatusTone;
+}
+
+/**
+ * A persistent, substantial item that needs examination or a decision, with optional details and
+ * actions. Use Alert for current status, InfoBox for optional guidance, and InsetPanel for grouping.
+ */
+export function NoticeCard({
+    actions,
+    badge,
+    children,
+    description,
+    footer,
+    icon,
+    level = 'h2',
+    title,
+    tone,
+}: NoticeCardProps) {
+    const id = useId();
+
+    return (
+        <article
+            aria-labelledby={id}
+            className={`border-base-300 bg-base-100 rounded-lg border border-l-4 p-4 sm:p-5 ${accentClasses[tone]}`}
+        >
+            <div className="flex min-w-0 gap-3 sm:gap-4">
+                <span
+                    aria-hidden="true"
+                    className={`flex size-9 shrink-0 items-center justify-center rounded-lg [&>svg]:size-5 ${toneTileClasses[tone]}`}
+                >
+                    {icon}
+                </span>
+                <div className="flex min-w-0 flex-1 flex-col gap-3">
+                    <div className="flex min-w-0 flex-col gap-1">
+                        <div className="flex min-w-0 flex-wrap items-center justify-between gap-2">
+                            <Heading id={id} as={level} variant="title">
+                                {title}
+                            </Heading>
+                            {badge}
+                        </div>
+                        <Text tone="muted">{description}</Text>
+                    </div>
+                    {children}
+                    {actions ? <div className="flex flex-wrap items-center gap-2">{actions}</div> : null}
+                    {footer}
+                </div>
+            </div>
+        </article>
+    );
+}

package/src/display/PairingList.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+
+import { Text } from '../typography/Typography';
+
+export interface PairingListItem {
+    key: string;
+    /** Short ordinal such as `1` or `2-05`. */
+    position: string;
+    title: string;
+    /** A secondary fact aligned in its own column, such as a duration. */
+    detail?: string;
+    /** One line under the title; `warning` draws attention to a doubt. */
+    note?: string;
+    noteTone?: 'muted' | 'warning';
+    control: ReactNode;
+}
+
+/** Rows that pair a numbered item with a chosen counterpart, such as release tracks and files. */
+export function PairingList({ items, label }: { items: readonly PairingListItem[]; label: string }) {
+    return (
+        <ul aria-label={label} className="divide-base-300 border-base-300 bg-base-100 divide-y rounded-lg border">
+            {items.map((item) => (
+                <li
+                    key={item.key}
+                    className="grid min-w-0 grid-cols-[2.5rem_minmax(0,1fr)_auto] items-center gap-x-3 gap-y-2 px-3 py-2.5 sm:grid-cols-[2.5rem_minmax(0,1fr)_3.5rem_minmax(0,20rem)] sm:px-4"
+                >
+                    <Text as="span" tone="muted" className="tabular-nums">
+                        {item.position}
+                    </Text>
+                    <span className="min-w-0">
+                        <Text as="span" className="block" truncate title={item.title} variant="label">
+                            {item.title}
+                        </Text>
+                        {item.note ? (
+                            <Text
+                                as="span"
+                                className="block"
+                                truncate
+                                title={item.note}
+                                variant="caption"
+                                tone={item.noteTone === 'warning' ? 'warning' : 'muted'}
+                            >
+                                {item.note}
+                            </Text>
+                        ) : null}
+                    </span>
+                    <Text as="span" tone="muted" className="text-right tabular-nums">
+                        {item.detail ?? ''}
+                    </Text>
+                    <span className="col-span-3 min-w-0 sm:col-span-1">{item.control}</span>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/display/PathList.tsx

@@ -0,0 +1,16 @@
+import { Code } from '@ninna-ui/primitives';
+
+/** File paths as truncated code, one per line. */
+export function PathList({ label, paths }: { label: string; paths: readonly { key: string; path: string }[] }) {
+    return (
+        <ul aria-label={label} className="space-y-1">
+            {paths.map(({ key, path }) => (
+                <li key={key} className="min-w-0">
+                    <Code title={path} className="block max-w-full truncate text-xs">
+                        {path}
+                    </Code>
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/display/PeoplePreview.tsx

@@ -0,0 +1,66 @@
+import { type ReactNode, useLayoutEffect, useRef, useState } from 'react';
+
+import { ImageCard } from './ImageCard';
+
+interface PeoplePreviewItem {
+    id: string;
+    name: string;
+    role: string;
+    artwork: ReactNode;
+    href?: string;
+}
+
+/** Render only the cards that fit in one row, including keyboard navigation. */
+export function PeoplePreview({
+    label,
+    items,
+    onNavigate,
+}: {
+    label: string;
+    items: readonly PeoplePreviewItem[];
+    onNavigate?: (href: string) => void;
+}) {
+    const rowRef = useRef<HTMLUListElement>(null);
+    const [visibleCount, setVisibleCount] = useState<number>();
+
+    useLayoutEffect(() => {
+        const row = rowRef.current;
+
+        if (!row) return;
+
+        const measure = () => {
+            const columns = getComputedStyle(row).gridTemplateColumns;
+
+            if (columns && !columns.includes('repeat(') && columns !== 'none')
+                setVisibleCount(columns.trim().split(/\s+/).length);
+        };
+        const observer = new ResizeObserver(measure);
+
+        measure();
+        observer.observe(row);
+
+        return () => observer.disconnect();
+    }, []);
+
+    return (
+        <ul
+            ref={rowRef}
+            aria-label={label}
+            className="grid min-w-0 grid-cols-[repeat(auto-fill,minmax(min(5.5rem,100%),1fr))] gap-x-3 gap-y-5"
+        >
+            {items.slice(0, visibleCount).map((person) => (
+                <li key={person.id} className="min-w-0">
+                    <ImageCard
+                        presentation="person"
+                        title={person.name}
+                        label={person.name}
+                        subtitle={person.role}
+                        artwork={person.artwork}
+                        href={person.href}
+                        onNavigate={onNavigate}
+                    />
+                </li>
+            ))}
+        </ul>
+    );
+}

package/src/display/PropertySheet.tsx

@@ -0,0 +1,180 @@
+import { ChevronDownIcon } from 'lucide-react';
+/* oxlint-disable react/only-export-components -- Compound members are exported through PropertySheet. */
+import { type ReactNode, useId } from 'react';
+
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+import { Heading, Text } from '../typography/Typography';
+import { BadgeList, type BadgeListItem } from './BadgeList';
+import { InsetPanel } from './InsetPanel';
+
+type PropertySheetProps = { title: string } & (
+    | { children: ReactNode; loading?: false; loadingLabel?: never }
+    | { children?: never; loading: true; loadingLabel?: string }
+);
+
+/** A titled sheet of facts about one thing; the body is label/value rows, a row of tags, or a short note. */
+function PropertySheetRoot({ children, loading = false, loadingLabel, title }: PropertySheetProps) {
+    const id = useId();
+    const content = (
+        <section
+            aria-labelledby={loading ? undefined : id}
+            aria-hidden={(loading && !loadingLabel) || undefined}
+            className="min-w-0"
+        >
+            <Heading
+                id={id}
+                as="h3"
+                variant="label"
+                tone="muted"
+                className="px-1"
+                loading={loading}
+                aria-hidden={loading || undefined}
+            >
+                {title}
+            </Heading>
+            <div className="mt-3">
+                <InsetPanel presentation="settings">{loading ? <PropertySheetRows loading /> : children}</InsetPanel>
+            </div>
+        </section>
+    );
+
+    return loading && loadingLabel ? <SkeletonLoader label={loadingLabel}>{content}</SkeletonLoader> : content;
+}
+
+interface PropertySheetRow {
+    label: string;
+    value: ReactNode;
+}
+
+type RowsProps = { loading: true; items?: never } | { loading?: false; items: readonly PropertySheetRow[] };
+
+function PropertySheetRows({ items, loading = false }: RowsProps) {
+    const rows = items ?? Array.from({ length: 3 }, () => ({ label: '', value: '' }));
+
+    return (
+        <dl className="divide-base-300 divide-y">
+            {rows.map(({ label, value }, index) => (
+                <div
+                    key={loading ? index : label}
+                    className="grid grid-cols-[minmax(0,1fr)_minmax(0,1.5fr)] items-baseline gap-x-6 px-4 py-2.5 sm:px-5"
+                >
+                    <dt>
+                        <Text as="span" tone="muted" loading={loading}>
+                            {label}
+                        </Text>
+                    </dt>
+                    <dd className="min-w-0 text-right">
+                        <Text as="span" className="wrap-break-word tabular-nums" variant="label" loading={loading}>
+                            {value}
+                        </Text>
+                    </dd>
+                </div>
+            ))}
+        </dl>
+    );
+}
+
+type PropertySheetTag = Omit<BadgeListItem, 'struck'>;
+
+function PropertySheetTags({ items }: { items: readonly PropertySheetTag[] }) {
+    return (
+        <div className="px-4 py-3 sm:px-5">
+            <BadgeList items={items} />
+        </div>
+    );
+}
+
+function PropertySheetNote({ children }: { children: ReactNode }) {
+    return (
+        <Text className="px-4 py-3 sm:px-5" tone="muted">
+            {children}
+        </Text>
+    );
+}
+
+function PropertySheetCollapsible({
+    children,
+    title,
+    summary,
+}: {
+    children: ReactNode;
+    title: string;
+    summary?: string;
+}) {
+    const id = useId();
+
+    return (
+        <section aria-labelledby={id} className="min-w-0">
+            <InsetPanel presentation="settings">
+                <details className="group/sheet">
+                    <summary className="hover:bg-base-100 focus-visible:outline-primary flex cursor-pointer list-none items-center gap-4 px-4 py-4 focus-visible:outline-2 focus-visible:-outline-offset-2 sm:px-5 [&::-webkit-details-marker]:hidden">
+                        <span className="min-w-0 flex-1 wrap-anywhere">
+                            <Text as="span" id={id} variant="label" className="block">
+                                {title}
+                            </Text>
+                            {summary ? (
+                                <Text as="span" tone="muted" variant="caption" className="mt-1 block">
+                                    {summary}
+                                </Text>
+                            ) : null}
+                        </span>
+                        <span
+                            aria-hidden="true"
+                            className="shrink-0 transition-transform group-open/sheet:rotate-180 [&>svg]:size-4"
+                        >
+                            <ChevronDownIcon />
+                        </span>
+                    </summary>
+                    <div className="border-base-300 border-t p-4 sm:p-5">{children}</div>
+                </details>
+            </InsetPanel>
+        </section>
+    );
+}
+
+function PropertySheetTable({
+    label,
+    columns,
+    rows,
+}: {
+    label: string;
+    columns: readonly string[];
+    rows: readonly { key: string; cells: readonly ReactNode[] }[];
+}) {
+    return (
+        <div className="overflow-x-auto" tabIndex={0}>
+            <table aria-label={label} className="w-full min-w-[30rem] table-fixed border-collapse text-left text-sm">
+                <thead className="border-base-300 text-base-700 border-b text-xs">
+                    <tr>
+                        {columns.map((column) => (
+                            <th key={column} scope="col" className="px-4 py-3 font-medium sm:px-5">
+                                {column}
+                            </th>
+                        ))}
+                    </tr>
+                </thead>
+                <tbody className="divide-base-300 divide-y">
+                    {rows.map((row) => (
+                        <tr key={row.key}>
+                            {row.cells.map((cell, index) => (
+                                <td key={index} className="px-4 py-3 align-top wrap-anywhere sm:px-5">
+                                    {cell}
+                                </td>
+                            ))}
+                        </tr>
+                    ))}
+                </tbody>
+            </table>
+        </div>
+    );
+}
+
+export const PropertySheet = Object.assign(PropertySheetRoot, {
+    Collapsible: PropertySheetCollapsible,
+    Note: PropertySheetNote,
+    Rows: PropertySheetRows,
+    Table: PropertySheetTable,
+    Tags: PropertySheetTags,
+});
+
+export type { PropertySheetRow, PropertySheetTag };

package/src/display/QrCode.tsx

@@ -0,0 +1,47 @@
+import { useEffect, useState } from 'react';
+
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+
+/** Encodes locally; the value is never sent to a QR service. */
+export function QrCode({ label, value }: { label: string; value: string }) {
+    const [encoded, setEncoded] = useState<{ source: string | null; value: string }>();
+
+    useEffect(() => {
+        let active = true;
+
+        void import('qrcode-generator')
+            .then(({ default: createQrCode }) => {
+                try {
+                    const code = createQrCode(0, 'M');
+
+                    code.addData(value, 'Byte');
+                    code.make();
+
+                    if (active) setEncoded({ source: code.createDataURL(4), value });
+                } catch {
+                    // The copyable value remains available if it exceeds QR capacity.
+                    if (active) setEncoded({ source: null, value });
+                }
+            })
+            .catch(() => {
+                // The copyable value remains usable if this optional chunk fails to load.
+                if (active) setEncoded({ source: null, value });
+            });
+
+        return () => {
+            active = false;
+        };
+    }, [value]);
+
+    if (encoded?.value !== value) {
+        return (
+            <SkeletonLoader label={label}>
+                <SkeletonLoader.Shape presentation="artwork" />
+            </SkeletonLoader>
+        );
+    }
+
+    return encoded.source ? (
+        <img alt={label} src={encoded.source} className="block w-full max-w-sm rounded-lg bg-white" />
+    ) : null;
+}

package/src/display/RadioChoice.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+
+import { tabbable } from '../foundations/KeyboardFocus';
+
+export function RadioChoice({
+    name,
+    checked,
+    onChange,
+    children,
+    trailing,
+}: {
+    name: string;
+    checked: boolean;
+    onChange: () => void;
+    children: ReactNode;
+    trailing?: ReactNode;
+}) {
+    return (
+        <div className="hover:bg-base-100 has-checked:bg-primary/10 has-focus-visible:ring-primary flex min-w-0 items-center gap-3 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-inset has-disabled:opacity-60">
+            <label className="flex min-w-0 flex-1 cursor-pointer items-center gap-3 px-4 py-3 has-disabled:cursor-default">
+                <input
+                    {...tabbable}
+                    type="radio"
+                    name={name}
+                    checked={checked}
+                    onChange={onChange}
+                    className="accent-primary size-4 shrink-0"
+                />
+                <span className="min-w-0 flex-1">{children}</span>
+            </label>
+            {trailing ? <div className="flex shrink-0 items-center gap-3 pr-4">{trailing}</div> : null}
+        </div>
+    );
+}

package/src/display/RatingLink.tsx

@@ -0,0 +1,76 @@
+import { CheckIcon } from 'lucide-react';
+
+import { Link } from '../typography/Link';
+import { Text } from '../typography/Typography';
+
+/** The sources' own marks and colors, as the Apple apps draw them. Anything else reads by its name. */
+function ratingMark(source: string) {
+    switch (source.trim().toLowerCase()) {
+        case 'trakt':
+            return {
+                name: 'Trakt',
+                label: 'Trakt',
+                mark: (
+                    <span className="inline-flex size-5 items-center justify-center rounded-full bg-[#ed1c24] text-white [&>svg]:size-3 [&>svg]:stroke-[3]">
+                        <CheckIcon />
+                    </span>
+                ),
+            };
+        case 'imdb':
+            return {
+                name: 'IMDb',
+                mark: (
+                    <span className="inline-flex h-5 items-center rounded-sm bg-[#f5c518] px-1 text-xs font-black text-black">
+                        IMDb
+                    </span>
+                ),
+            };
+        case 'rotten tomatoes critics':
+            return { name: 'Tomatometer', mark: <span>🍅</span> };
+        case 'rotten tomatoes audience':
+            return { name: 'Popcornmeter', mark: <span>🍿</span> };
+        default:
+            return { name: source, label: source, mark: null };
+    }
+}
+
+/** A provider's mark and its score, linked to the original rating. */
+export function RatingLink({
+    source,
+    value,
+    scale,
+    href,
+}: {
+    source: string;
+    /** The score as it reads, such as "6.5" or "57%". */
+    value: string;
+    /** The scale shown after the score, such as "/ 10"; none for percentages. */
+    scale?: string;
+    href: string;
+}) {
+    const { name, label, mark } = ratingMark(source);
+
+    return (
+        <Link
+            href={href}
+            external
+            aria-label={[name, value, scale].filter(Boolean).join(' ')}
+            className="max-w-full gap-1.5"
+        >
+            {mark ? <span aria-hidden="true">{mark}</span> : null}
+            {label ? (
+                <Text as="span" variant="caption" aria-hidden="true">
+                    {label}
+                </Text>
+            ) : null}
+            <Text as="span" variant="label" className="tabular-nums">
+                {value}
+            </Text>
+            {scale ? (
+                <Text as="span" variant="caption" tone="muted" className="tabular-nums">
+                    {scale}
+                </Text>
+            ) : null}
+        </Link>
+    );
+}