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

package/src/layout/AppShell.tsx

@@ -0,0 +1,63 @@
+import { type ReactNode, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+interface AppShellProps {
+    children: ReactNode;
+    header: ReactNode;
+}
+
+/** The page frame: a column whose header sticks to the top as glass. The document itself
+ *  scrolls, so content passes under the header and Safari tints its toolbar to match. The header's hairline
+ *  appears once the page has scrolled, as on t3.codes. */
+export function AppShell({ children, header }: AppShellProps) {
+    const shell = useRef<HTMLDivElement>(null);
+    const headerContainer = useRef<HTMLDivElement>(null);
+    const scrolled = useDocumentScrolled();
+
+    useLayoutEffect(() => {
+        const container = headerContainer.current;
+        const root = shell.current;
+
+        if (!container || !root) return;
+
+        const measure = () => {
+            root.style.setProperty('--lar-header-height', `${container.getBoundingClientRect().height}px`);
+        };
+        const observer = new ResizeObserver(measure);
+
+        observer.observe(container);
+        measure();
+
+        return () => observer.disconnect();
+    }, []);
+
+    return (
+        <div
+            ref={shell}
+            className="flex min-h-dvh min-w-0 flex-col pr-[env(safe-area-inset-right)] pl-[env(safe-area-inset-left)]"
+        >
+            <div
+                ref={headerContainer}
+                data-scrolled={scrolled || undefined}
+                className="glass-bar data-scrolled:border-base-300 sticky top-0 z-50 shrink-0 border-b border-transparent pt-[env(safe-area-inset-top)] transition-[border-color] duration-300"
+            >
+                {header}
+            </div>
+            {children}
+        </div>
+    );
+}
+
+function useDocumentScrolled() {
+    const [scrolled, setScrolled] = useState(false);
+
+    useEffect(() => {
+        const update = () => setScrolled(window.scrollY > 2);
+
+        update();
+        window.addEventListener('scroll', update, { passive: true });
+
+        return () => window.removeEventListener('scroll', update);
+    }, []);
+
+    return scrolled;
+}

package/src/layout/AuthLayout.tsx

@@ -0,0 +1,40 @@
+import { type ReactNode, useId } from 'react';
+
+import { BrandMark } from '../display/BrandMark';
+import { Heading, Text } from '../typography/Typography';
+import { Inline, Stack } from './Flow';
+
+interface AuthLayoutProps {
+    brandLabel: string;
+    children: ReactNode;
+    description?: string;
+    title: string;
+}
+
+/** A page-centered card for signing in or first-run setup, shown before the app shell exists. */
+export function AuthLayout({ brandLabel, children, description, title }: AuthLayoutProps) {
+    const titleId = useId();
+
+    return (
+        <main className="flex min-h-dvh items-center justify-center px-4 py-10">
+            <section
+                aria-labelledby={titleId}
+                className="border-base-300 bg-base-100 w-full max-w-sm rounded-2xl border p-6 shadow-[0_24px_64px_-32px_rgb(0_0_0/35%)] sm:p-8"
+            >
+                <Stack space="page">
+                    <Stack space="related" className="items-center text-center">
+                        <Inline align="baseline" space="tight" className="text-xl leading-none">
+                            <BrandMark label={brandLabel} />
+                            <span className="font-medium">Server</span>
+                        </Inline>
+                        <Heading id={titleId} as="h1" variant="section">
+                            {title}
+                        </Heading>
+                        {description ? <Text tone="muted">{description}</Text> : null}
+                    </Stack>
+                    {children}
+                </Stack>
+            </section>
+        </main>
+    );
+}

package/src/layout/ContentContainer.tsx

@@ -0,0 +1,16 @@
+import { Container } from '@ninna-ui/layout';
+import type { ReactNode } from 'react';
+
+interface ContentContainerProps {
+    as?: 'div' | 'main';
+    children: ReactNode;
+    className?: string;
+}
+
+export function ContentContainer({ as = 'div', children, className }: ContentContainerProps) {
+    return (
+        <Container as={as} maxWidth="full" padding={false} className={className ? `px-4 ${className}` : 'px-4'}>
+            {children}
+        </Container>
+    );
+}

package/src/layout/Flow.tsx

@@ -0,0 +1,56 @@
+import {
+    Flex as NinnaFlex,
+    type FlexProps,
+    Grid as NinnaResponsiveGrid,
+    SimpleGrid as NinnaGrid,
+    Stack as NinnaStack,
+    type StackProps as NinnaStackProps,
+} from '@ninna-ui/layout';
+import type { ComponentProps, ElementType } from 'react';
+
+const spacing = { none: '0', tight: '1', related: '2', group: '3', section: '4', page: '6' } as const;
+
+export type FlowSpace = keyof typeof spacing;
+
+export type StackProps<C extends ElementType = 'div'> = Omit<NinnaStackProps<C>, 'gap' | 'direction'> & {
+    space?: FlowSpace;
+};
+
+export function Stack<C extends ElementType = 'div'>({ space = 'group', ...props }: StackProps<C>) {
+    return <NinnaStack {...(props as NinnaStackProps<C>)} gap={spacing[space]} />;
+}
+
+type InlineProps<C extends ElementType> = Omit<FlexProps<C>, 'gap' | 'direction' | 'wrap'> & {
+    space?: FlowSpace;
+    wrap?: boolean;
+};
+
+export function Inline<C extends ElementType = 'div'>({ space = 'related', wrap, ...props }: InlineProps<C>) {
+    return <NinnaFlex {...(props as FlexProps<C>)} gap={spacing[space]} wrap={wrap ? 'wrap' : 'nowrap'} />;
+}
+
+type GridProps = Omit<ComponentProps<typeof NinnaGrid>, 'gap' | 'minChildWidth' | 'columns'> & {
+    variant?: 'metrics' | 'content' | 'overview' | 'details' | 'pairs' | 'posters';
+};
+
+export function Grid({ variant = 'content', ...props }: GridProps) {
+    if (variant === 'posters')
+        return (
+            <NinnaGrid
+                {...props}
+                gap="4"
+                style={{ gridTemplateColumns: 'repeat(auto-fill, minmax(min(6.5rem, 100%), 1fr))' }}
+            />
+        );
+
+    if (variant === 'details') return <NinnaResponsiveGrid {...props} gap="6" columns={{ base: 1, md: 2 }} />;
+
+    if (variant === 'pairs') return <NinnaResponsiveGrid {...props} gap="3" columns={{ base: 1, lg: 2 }} />;
+
+    if (variant === 'overview')
+        return <NinnaResponsiveGrid {...props} gap="3" columns={{ base: 1, md: 2, lg: 3, '2xl': 4 }} />;
+
+    return (
+        <NinnaGrid {...props} gap="3" minChildWidth={variant === 'metrics' ? 'min(11rem, 100%)' : 'min(16rem, 100%)'} />
+    );
+}

package/src/layout/PageLayout.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import { Heading, Text } from '../typography/Typography';
+import { ContentContainer } from './ContentContainer';
+import { Stack } from './Flow';
+
+interface PageLayoutProps {
+    label?: string;
+    children?: ReactNode;
+    header?: ReactNode;
+    title?: string;
+    description?: ReactNode;
+    variant?: 'default' | 'detail';
+}
+
+export function PageLayout({ children, header, title, description, label, variant = 'default' }: PageLayoutProps) {
+    return (
+        <main aria-label={label} className="flex min-w-0 flex-1 flex-col [--lar-page-gutter:--spacing(4)]">
+            {header}
+            <ContentContainer className="pt-(--lar-page-gutter) pb-10 md:pb-12">
+                <Stack space={variant === 'detail' ? 'page' : 'section'}>
+                    {title ? (
+                        <Stack space="related">
+                            <Heading as="h1" variant="page">
+                                {title}
+                            </Heading>
+                            {description ? <Text tone="muted">{description}</Text> : null}
+                        </Stack>
+                    ) : null}
+                    {children}
+                </Stack>
+            </ContentContainer>
+        </main>
+    );
+}

package/src/layout/PageSection.tsx

@@ -0,0 +1,103 @@
+import { type ReactNode, useId } from 'react';
+
+import { Heading, Text } from '../typography/Typography';
+
+const widths = {
+    narrow: 'max-w-[880px]',
+    default: 'max-w-[1200px]',
+} as const;
+
+const spacing = {
+    hero: 'pt-16 pb-20 sm:pt-24 sm:pb-28',
+    default: 'py-12 sm:py-20',
+    tight: 'py-12 sm:py-20',
+    /** The last band before the footer, which follows a full section. */
+    closing: 'pt-0 pb-14 sm:pb-20',
+} as const;
+
+interface PageSectionProps {
+    children: ReactNode;
+    id?: string;
+    width?: keyof typeof widths;
+    space?: keyof typeof spacing;
+    /** A raised band separates a section from the ones around it. */
+    tone?: 'plain' | 'raised';
+    /** Names the section for assistive technology when it has no SectionHeading. */
+    label?: string;
+    background?: ReactNode;
+    /** The section's SectionHeading, set above the content with room to breathe. */
+    heading?: ReactNode;
+}
+
+/** One band of a marketing page, centred in the page column. */
+export function PageSection({
+    children,
+    id,
+    width = 'default',
+    space = 'default',
+    tone = 'plain',
+    label,
+    background,
+    heading,
+}: PageSectionProps) {
+    return (
+        <section
+            id={id}
+            aria-label={label}
+            className={`relative isolate scroll-mt-16 ${tone === 'raised' ? 'border-base-300/80 bg-base-100/70 dark:bg-base-100/50 border-y' : ''}`}
+        >
+            {background}
+            <div className={`mx-auto w-full px-5 sm:px-8 ${widths[width]} ${spacing[space]}`}>
+                {heading ? <div className="lar-reveal mb-8 sm:mb-16">{heading}</div> : null}
+                {children}
+            </div>
+        </section>
+    );
+}
+
+interface SectionHeadingProps {
+    eyebrow?: string;
+    title: ReactNode;
+    lead?: ReactNode;
+    align?: 'center' | 'start';
+    level?: 'h1' | 'h2';
+    size?: 'display' | 'headline';
+}
+
+/** The eyebrow, title and lead that open a section. */
+export function SectionHeading({
+    eyebrow,
+    title,
+    lead,
+    align = 'center',
+    level = 'h2',
+    size = 'headline',
+}: SectionHeadingProps) {
+    const id = useId();
+
+    return (
+        <header
+            aria-labelledby={id}
+            className={`flex flex-col gap-4 ${align === 'center' ? 'mx-auto max-w-[760px] items-center text-center' : 'max-w-[640px]'}`}
+        >
+            {eyebrow ? <Eyebrow>{eyebrow}</Eyebrow> : null}
+            <Heading id={id} as={level} variant={size}>
+                {title}
+            </Heading>
+            {lead ? (
+                <Text variant="lead" tone="muted" className={align === 'center' ? 'max-w-[620px]' : ''}>
+                    {lead}
+                </Text>
+            ) : null}
+        </header>
+    );
+}
+
+/** A short label above a title, in the brand navy. */
+export function Eyebrow({ children }: { children: ReactNode }) {
+    return (
+        <span className="text-primary text-[13px] font-semibold tracking-[-0.005em] dark:text-[color-mix(in_srgb,var(--color-primary)_50%,white)]">
+            {children}
+        </span>
+    );
+}

package/src/layout/ScrollArea.tsx

@@ -0,0 +1,7 @@
+import type { ComponentPropsWithoutRef } from 'react';
+
+export type ScrollAreaProps = Omit<ComponentPropsWithoutRef<'div'>, 'className' | 'style'>;
+
+export function ScrollArea(props: ScrollAreaProps) {
+    return <div {...props} className="max-h-64 min-h-0 overflow-y-auto overscroll-contain pr-1" />;
+}

package/src/layout/Section.tsx

@@ -0,0 +1,36 @@
+import { type ReactNode, useId } from 'react';
+
+import { Badge } from '../display/Badge';
+import { Heading, Text } from '../typography/Typography';
+import { Inline, Stack } from './Flow';
+
+interface SectionProps {
+    title: string;
+    description?: ReactNode;
+    count?: ReactNode;
+    actions?: ReactNode;
+    children: ReactNode;
+    level?: 'h2' | 'h3' | 'h4';
+}
+
+export function Section({ title, description, count, actions, children, level = 'h2' }: SectionProps) {
+    const id = useId();
+
+    return (
+        <Stack as="section" space="section" aria-labelledby={id}>
+            <Stack space="tight">
+                <Inline justify="between" align="center">
+                    <Inline align="center">
+                        <Heading id={id} as={level} variant={level === 'h2' ? 'section' : 'subsection'}>
+                            {title}
+                        </Heading>
+                        {count != null ? <Badge>{count}</Badge> : null}
+                    </Inline>
+                    {actions}
+                </Inline>
+                {description ? <Text tone="muted">{description}</Text> : null}
+            </Stack>
+            {children}
+        </Stack>
+    );
+}

package/src/layout/Site.tsx

@@ -0,0 +1,205 @@
+import { MenuIcon, XIcon } from 'lucide-react';
+import { type ReactNode, useEffect, useState } from 'react';
+
+import { tabbable } from '../foundations/KeyboardFocus';
+
+export interface SiteLink {
+    label: string;
+    href: string;
+    current?: boolean;
+    external?: boolean;
+}
+
+interface SiteShellProps {
+    skipLabel: string;
+    header: ReactNode;
+    footer: ReactNode;
+    children: ReactNode;
+}
+
+/** The website frame: a glass header that stays on top while the document scrolls under it, then the footer. */
+export function SiteShell({ skipLabel, header, footer, children }: SiteShellProps) {
+    const scrolled = useScrolled();
+
+    return (
+        <div className="flex min-h-dvh min-w-0 flex-col overflow-x-clip pr-[env(safe-area-inset-right)] pl-[env(safe-area-inset-left)]">
+            <a
+                href="#content"
+                className="bg-base-100 sr-only z-[60] rounded-md px-3 py-2 text-sm font-medium focus:not-sr-only focus:fixed focus:top-3 focus:left-3"
+            >
+                {skipLabel}
+            </a>
+            <div
+                data-scrolled={scrolled || undefined}
+                className="glass-bar data-scrolled:border-base-300 sticky top-0 z-50 shrink-0 border-b border-transparent pt-[env(safe-area-inset-top)] transition-[border-color] duration-300"
+            >
+                {header}
+            </div>
+            <main id="content" className="flex-1">
+                {children}
+            </main>
+            {footer}
+        </div>
+    );
+}
+
+interface SiteHeaderProps {
+    brand: ReactNode;
+    links: readonly SiteLink[];
+    actions: ReactNode;
+    /** Secondary controls, such as the theme switch: in the bar on wide screens and in the menu on narrow ones. */
+    utilities?: ReactNode;
+    menuLabel: string;
+    closeMenuLabel: string;
+    navigationLabel: string;
+    onNavigate: (href: string) => void;
+}
+
+export function SiteHeader({
+    brand,
+    links,
+    actions,
+    utilities,
+    menuLabel,
+    closeMenuLabel,
+    navigationLabel,
+    onNavigate,
+}: SiteHeaderProps) {
+    const [open, setOpen] = useState(false);
+
+    function follow(href: string) {
+        setOpen(false);
+        onNavigate(href);
+    }
+
+    return (
+        <header className="mx-auto flex h-14 w-full max-w-[1200px] items-center gap-6 px-5 sm:px-8">
+            {brand}
+            <nav aria-label={navigationLabel} className="hidden items-center gap-1 md:flex">
+                {links.map((link) => (
+                    <NavLink key={link.href} link={link} onNavigate={follow} />
+                ))}
+            </nav>
+            <div className="ml-auto flex items-center gap-2 max-sm:[&>a]:hidden">
+                {utilities ? <div className="hidden md:contents">{utilities}</div> : null}
+                {actions}
+            </div>
+            <button
+                {...tabbable}
+                type="button"
+                aria-expanded={open}
+                aria-controls="site-menu"
+                aria-label={open ? closeMenuLabel : menuLabel}
+                onClick={() => setOpen((value) => !value)}
+                className="text-base-800 hover:bg-base-200 -mr-2 inline-flex size-9 items-center justify-center rounded-md transition-colors md:hidden [&_svg]:size-5"
+            >
+                {open ? <XIcon /> : <MenuIcon />}
+            </button>
+            {open ? (
+                <nav
+                    id="site-menu"
+                    aria-label={navigationLabel}
+                    className="glass-menu absolute inset-x-3 top-[calc(100%+0.5rem)] flex flex-col gap-1 rounded-2xl p-2 md:hidden"
+                >
+                    {links.map((link) => (
+                        <NavLink key={link.href} link={link} onNavigate={follow} large />
+                    ))}
+                    {utilities ? <div className="border-base-300 mt-1 border-t px-3 pt-3 pb-1">{utilities}</div> : null}
+                </nav>
+            ) : null}
+        </header>
+    );
+}
+
+function NavLink({ link, onNavigate, large }: { link: SiteLink; onNavigate: (href: string) => void; large?: boolean }) {
+    return (
+        <a
+            {...tabbable}
+            href={link.href}
+            aria-current={link.current ? 'page' : undefined}
+            {...(link.external ? { target: '_blank', rel: 'noreferrer' } : {})}
+            onClick={(event) => {
+                if (link.external || event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0) return;
+
+                event.preventDefault();
+                onNavigate(link.href);
+            }}
+            className={`text-base-700 hover:text-base-content aria-[current=page]:text-base-content focus-visible:outline-primary rounded-md font-medium transition-colors focus-visible:outline-2 ${large ? 'hover:bg-base-200 px-3 py-2.5 text-base' : 'px-2.5 py-1.5 text-sm'}`}
+        >
+            {link.label}
+        </a>
+    );
+}
+
+interface SiteFooterProps {
+    brand: ReactNode;
+    tagline: string;
+    columns: readonly { title: string; links: readonly SiteLink[] }[];
+    legal: string;
+    note: ReactNode;
+    onNavigate: (href: string) => void;
+}
+
+export function SiteFooter({ brand, tagline, columns, legal, note, onNavigate }: SiteFooterProps) {
+    return (
+        <footer className="border-base-300 bg-base-50 border-t">
+            <div className="mx-auto grid w-full max-w-[1200px] grid-cols-2 gap-x-6 gap-y-10 px-5 pt-14 pb-10 sm:px-8 md:grid-cols-[1.4fr_repeat(4,1fr)]">
+                <div className="col-span-2 flex flex-col gap-3 md:col-span-1">
+                    {brand}
+                    <p className="text-base-700 max-w-64 text-sm leading-6">{tagline}</p>
+                </div>
+                {columns.map((column) => (
+                    <div key={column.title} className="flex flex-col gap-3">
+                        <h2 className="text-base-800 text-xs font-semibold tracking-[0.06em] uppercase">
+                            {column.title}
+                        </h2>
+                        <ul className="flex flex-col gap-2">
+                            {column.links.map((link) => (
+                                <li key={link.href}>
+                                    <a
+                                        {...tabbable}
+                                        href={link.href}
+                                        {...(link.external ? { target: '_blank', rel: 'noreferrer' } : {})}
+                                        onClick={(event) => {
+                                            if (link.external || !link.href.startsWith('/')) return;
+
+                                            if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                                                return;
+
+                                            event.preventDefault();
+                                            onNavigate(link.href);
+                                        }}
+                                        className="text-base-700 hover:text-base-content text-sm transition-colors"
+                                    >
+                                        {link.label}
+                                    </a>
+                                </li>
+                            ))}
+                        </ul>
+                    </div>
+                ))}
+            </div>
+            <div className="mx-auto w-full max-w-[1200px] px-5 sm:px-8">
+                <div className="border-base-300/70 text-base-700 flex flex-col gap-2 border-t py-6 text-xs sm:flex-row sm:items-center sm:justify-between">
+                    <span>{legal}</span>
+                    <span>{note}</span>
+                </div>
+            </div>
+        </footer>
+    );
+}
+
+function useScrolled() {
+    const [scrolled, setScrolled] = useState(false);
+
+    useEffect(() => {
+        const update = () => setScrolled(window.scrollY > 4);
+
+        update();
+        window.addEventListener('scroll', update, { passive: true });
+
+        return () => window.removeEventListener('scroll', update);
+    }, []);
+
+    return scrolled;
+}

package/src/layout/TitleBar.tsx

@@ -0,0 +1,97 @@
+import { ChevronDownIcon, ChevronRightIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { useDesignSystemLabels } from '../foundations/DesignSystemProvider';
+import { tabbable } from '../foundations/KeyboardFocus';
+
+interface TitleBarProps {
+    actions?: ReactNode;
+    /** The brand, a link home, before a divider and the title. */
+    brand: ReactNode;
+    search?: ReactNode;
+    title: ReactNode;
+}
+
+/** T3 Code's 52px title bar: the brand and where you are on the left, tools on the right. Its own width,
+ *  not the window's, decides when search folds to an icon; narrow screens close the gaps so the title keeps
+ *  the room left. */
+export function TitleBar({ actions, brand, search, title }: TitleBarProps) {
+    const labels = useDesignSystemLabels();
+
+    return (
+        <header
+            aria-label={labels.toolbar}
+            className="@container relative flex h-13 min-w-0 items-center gap-1 px-3 sm:gap-2 sm:px-4"
+        >
+            <div className="[&_a]:focus-visible:ring-primary flex shrink-0 items-center [&_a]:rounded-sm [&_a]:outline-none [&_a]:focus-visible:ring-2">
+                {brand}
+            </div>
+            <span aria-hidden="true" className="bg-base-300 mx-1 h-5 w-px shrink-0 max-sm:hidden" />
+            <div className="flex min-w-0 flex-1 items-center gap-1">{title}</div>
+            {search ? <div className="flex shrink-0">{search}</div> : null}
+            {actions ? <div className="flex shrink-0 items-center gap-1.5">{actions}</div> : null}
+        </header>
+    );
+}
+
+export interface TitleBarTrailItem {
+    key: string;
+    icon?: ReactNode;
+    label: string;
+    /** Makes the step a button, such as one switching to its siblings; `selectLabel` says where it leads. */
+    onSelect?: () => void;
+    selectLabel?: string;
+}
+
+/** The title bar's location, T3's "project / thread": each step muted and chevron-separated, the current one
+ *  in the foreground. Steps that switch somewhere are buttons with a chevron. Narrow screens show only the
+ *  current step. */
+export function TitleBarTrail({ items }: { items: readonly TitleBarTrailItem[] }) {
+    return (
+        <ol className="flex min-w-0 items-center gap-0.5 text-sm">
+            {items.map((item, index) => {
+                const last = index === items.length - 1;
+                const content = (
+                    <>
+                        {item.icon ? (
+                            <span className="text-base-700 flex shrink-0 [&_svg]:size-4">{item.icon}</span>
+                        ) : null}
+                        <span className="truncate">{item.label}</span>
+                    </>
+                );
+
+                return (
+                    <li
+                        key={item.key}
+                        aria-current={last ? 'page' : undefined}
+                        className={`flex min-w-0 items-center gap-0.5 ${last ? 'text-base-content font-medium' : 'text-base-700 hidden shrink-0 sm:flex'}`}
+                    >
+                        {index > 0 ? (
+                            <span aria-hidden="true" className="text-base-500 flex shrink-0 [&>svg]:size-3.5">
+                                <ChevronRightIcon />
+                            </span>
+                        ) : null}
+                        {item.onSelect ? (
+                            <button
+                                {...tabbable}
+                                type="button"
+                                aria-haspopup="dialog"
+                                aria-description={item.selectLabel}
+                                title={item.selectLabel}
+                                onClick={item.onSelect}
+                                className="hover:bg-base-200 hover:text-base-content focus-visible:outline-primary dark:hover:bg-base-300 flex h-7 min-w-0 items-center gap-2 rounded-lg px-2 transition-colors focus-visible:outline-2"
+                            >
+                                {content}
+                                <span aria-hidden="true" className="text-base-500 flex shrink-0 [&>svg]:size-3.5">
+                                    <ChevronDownIcon />
+                                </span>
+                            </button>
+                        ) : (
+                            <span className="flex min-w-0 items-center gap-2 px-2">{content}</span>
+                        )}
+                    </li>
+                );
+            })}
+        </ol>
+    );
+}