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

package/src/overlays/CommandPalette.tsx

@@ -0,0 +1,199 @@
+/* oxlint-disable react/only-export-components -- The option hook belongs to the palette. */
+
+import { Modal as NinnaModal } from '@ninna-ui/overlays';
+import { SearchIcon, XIcon } from 'lucide-react';
+import { createContext, type ReactNode, useContext, useEffect, useId, useRef, useState } from 'react';
+
+import { IconButton } from '../actions/IconButton';
+import { ResultList } from '../collections/ResultList';
+import { useDesignSystemLabels } from '../foundations/DesignSystemProvider';
+import { Text } from '../typography/Typography';
+import { useModalAutoFocus } from './useModalAutoFocus';
+import { useScrollFade } from './useScrollFade';
+
+interface CommandPaletteProps {
+    /** The dialog's accessible title and description; the field says the rest. */
+    label: string;
+    description: string;
+    placeholder: string;
+    query: string;
+    onQueryChange: (query: string) => void;
+    /** Narrows the list to one level, shown as a chip before the field; Backspace in an empty field leaves it. */
+    scope?: { label: string; leaveLabel: string; onLeave: () => void };
+    /** The options' values in list order, for the arrow keys and Enter. */
+    options: readonly string[];
+    onSelect: (value: string) => void;
+    onClose: () => void;
+    listLabel: string;
+    busy?: boolean;
+    /** Shown when nothing is listed. */
+    empty?: ReactNode;
+    /** Quiet key hints under the list, on screens with a keyboard. */
+    footer?: ReactNode;
+    children: ReactNode;
+}
+
+const OptionContext = createContext<{
+    listId: string;
+    activeValue: string | undefined;
+    setActiveValue: (value: string) => void;
+} | null>(null);
+
+/** T3 Code's command palette: a field over one keyboard list of grouped options, as a dialog over the page
+ *  or, on phones, the whole screen. The arrow keys move through `options`, Enter selects, Escape closes. */
+export function CommandPalette({
+    label,
+    description,
+    placeholder,
+    query,
+    onQueryChange,
+    scope,
+    options,
+    onSelect,
+    onClose,
+    listLabel,
+    busy = false,
+    empty,
+    footer,
+    children,
+}: CommandPaletteProps) {
+    const labels = useDesignSystemLabels();
+    const focusProps = useModalAutoFocus();
+    const { setViewport, setContent, className } = useScrollFade();
+    const listId = useId();
+    const input = useRef<HTMLInputElement>(null);
+    const [chosen, setActiveValue] = useState<string>();
+    // The highlight follows the list: when the chosen option leaves it, the first option takes over.
+    const activeValue = chosen !== undefined && options.includes(chosen) ? chosen : options[0];
+
+    useEffect(() => {
+        if (activeValue) document.getElementById(optionId(listId, activeValue))?.scrollIntoView({ block: 'nearest' });
+    }, [activeValue, listId]);
+
+    return (
+        <NinnaModal open onOpenChange={(open) => !open && onClose()}>
+            <NinnaModal.Content
+                title={label}
+                description={description}
+                centered={false}
+                {...focusProps}
+                className="flex max-h-[min(36rem,calc(100dvh-6rem))] w-[calc(100vw-2rem)] max-w-2xl flex-col overflow-hidden p-0 shadow-(--lar-shadow-dialog) max-sm:top-0 max-sm:left-0 max-sm:h-dvh max-sm:max-h-none max-sm:w-full max-sm:max-w-none max-sm:translate-x-0 max-sm:rounded-none! max-sm:border-0 max-sm:pt-[env(safe-area-inset-top)]"
+            >
+                <div className="border-base-300 [&>svg]:text-base-600 flex shrink-0 items-center gap-2 border-b px-4 py-3 [&>svg]:size-4 [&>svg]:shrink-0">
+                    <SearchIcon />
+                    {scope ? (
+                        <span className="bg-primary/12 text-primary flex shrink-0 items-center gap-1 rounded-md py-0.5 pr-1 pl-2 text-xs font-medium">
+                            {scope.label}
+                            <button
+                                type="button"
+                                tabIndex={-1}
+                                aria-label={scope.leaveLabel}
+                                className="hover:bg-primary/15 rounded-sm p-0.5 [&>svg]:size-3"
+                                onClick={() => {
+                                    scope.onLeave();
+                                    input.current?.focus();
+                                }}
+                            >
+                                <XIcon />
+                            </button>
+                        </span>
+                    ) : null}
+                    <input
+                        ref={input}
+                        role="combobox"
+                        aria-label={label}
+                        aria-expanded
+                        aria-controls={listId}
+                        aria-autocomplete="list"
+                        aria-activedescendant={activeValue ? optionId(listId, activeValue) : undefined}
+                        aria-busy={busy}
+                        placeholder={placeholder}
+                        value={query}
+                        className="text-base-content placeholder:text-base-600 min-w-0 flex-1 bg-transparent text-base outline-none sm:text-sm"
+                        onChange={(event) => onQueryChange(event.target.value)}
+                        onKeyDown={(event) => {
+                            if (event.nativeEvent.isComposing) return;
+
+                            if (event.key === 'Backspace' && !query && scope) {
+                                event.preventDefault();
+                                scope.onLeave();
+                            } else if ((event.key === 'ArrowDown' || event.key === 'ArrowUp') && options.length) {
+                                event.preventDefault();
+
+                                const index = activeValue ? options.indexOf(activeValue) : -1;
+                                const step = event.key === 'ArrowDown' ? 1 : -1;
+
+                                setActiveValue(options[(index + step + options.length) % options.length]!);
+                            } else if (event.key === 'Enter' && activeValue) {
+                                event.preventDefault();
+                                onSelect(activeValue);
+                            }
+                        }}
+                    />
+                    <span className="flex sm:hidden">
+                        <IconButton aria-label={labels.close} icon={<XIcon />} onClick={onClose} variant="header" />
+                    </span>
+                </div>
+                <div ref={setViewport} className={`min-h-0 flex-1 overflow-y-auto overscroll-contain p-2 ${className}`}>
+                    <div ref={setContent} className="flow-root">
+                        <OptionContext.Provider value={{ listId, activeValue, setActiveValue }}>
+                            <ResultList id={listId} label={listLabel} density="compact" aria-busy={busy}>
+                                {children}
+                            </ResultList>
+                        </OptionContext.Provider>
+                        {options.length === 0 && empty ? (
+                            <Text tone="muted" className="px-3 py-8 text-center">
+                                {empty}
+                            </Text>
+                        ) : null}
+                    </div>
+                </div>
+                {footer ? (
+                    <div className="border-base-300 text-2xs text-base-700 hidden shrink-0 items-center gap-4 border-t px-4 py-2 pointer-fine:flex">
+                        {footer}
+                    </div>
+                ) : null}
+            </NinnaModal.Content>
+        </NinnaModal>
+    );
+}
+
+/** A labelled run of options in the palette's list. */
+export function CommandPaletteGroup({ label, children }: { label: string; children: ReactNode }) {
+    const labelId = useId();
+
+    return (
+        <div role="group" aria-labelledby={labelId} className="flex flex-col gap-1 not-first:pt-2">
+            <Text
+                as="span"
+                id={labelId}
+                variant="caption"
+                tone="muted"
+                className="px-2 pt-1 font-medium tracking-wide uppercase"
+            >
+                {label}
+            </Text>
+            {children}
+        </div>
+    );
+}
+
+/** Props for a palette option, such as a `ResultRow`: its id, highlight and pointer tracking. */
+export function useCommandPaletteOption(value: string) {
+    const context = useContext(OptionContext);
+
+    if (!context) throw new Error('useCommandPaletteOption must be used inside CommandPalette');
+
+    return {
+        id: optionId(context.listId, value),
+        selected: context.activeValue === value,
+        tabIndex: -1,
+        onPointerMove: () => {
+            if (context.activeValue !== value) context.setActiveValue(value);
+        },
+    };
+}
+
+function optionId(listId: string, value: string) {
+    return `${listId}-${value.replace(/[^\w-]/g, '_')}`;
+}

package/src/overlays/Drawer.tsx

@@ -0,0 +1,107 @@
+/* oxlint-disable react/only-export-components -- Compound members are exported through Drawer. */
+import {
+    Drawer as NinnaDrawer,
+    type DrawerBodyProps,
+    type DrawerContentProps,
+    type DrawerFooterProps,
+} from '@ninna-ui/overlays';
+import { XIcon } from 'lucide-react';
+import { type ComponentProps, forwardRef, type ReactNode } from 'react';
+
+import { IconButton } from '../actions/IconButton';
+import { useDesignSystemLabels } from '../foundations/DesignSystemProvider';
+import { Heading, Text } from '../typography/Typography';
+import { useModalAutoFocus } from './useModalAutoFocus';
+
+interface DrawerContentPolicyProps extends Omit<DrawerContentProps, 'className' | 'placement' | 'size' | 'title'> {
+    title: string;
+    subtitle?: ReactNode;
+    /** Header controls shown before the close button. */
+    actions?: ReactNode;
+    /** Runs as the drawer closes; preventing its default keeps focus from returning to the opening control. */
+    onCloseAutoFocus?: (event: Event) => void;
+}
+
+function DrawerRoot(props: ComponentProps<typeof NinnaDrawer>) {
+    return <NinnaDrawer {...props} />;
+}
+
+const DrawerContent = forwardRef<HTMLDivElement, DrawerContentPolicyProps>(
+    ({ actions, children, description, subtitle, title, onCloseAutoFocus, ...props }, ref) => {
+        const labels = useDesignSystemLabels();
+        const autoFocus = useModalAutoFocus();
+        const focusProps = {
+            ...autoFocus,
+            onCloseAutoFocus: (event: Event) => {
+                onCloseAutoFocus?.(event);
+
+                if (!event.defaultPrevented) autoFocus.onCloseAutoFocus(event);
+            },
+        };
+
+        return (
+            <NinnaDrawer.Content
+                ref={ref}
+                {...props}
+                {...focusProps}
+                title={title}
+                description={description}
+                placement="right"
+                size="lg"
+                className="flex w-full max-w-xl flex-col overflow-hidden"
+            >
+                <header
+                    data-slot="drawer-header"
+                    className="border-base-300 shrink-0 border-b px-5 py-5 sm:px-6 sm:py-6"
+                >
+                    <div className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] items-start gap-4">
+                        <Heading as="h2" className="min-w-0 wrap-break-word" variant="section">
+                            {title}
+                        </Heading>
+                        <div className="flex items-center gap-1">
+                            {actions}
+                            <NinnaDrawer.Close asChild>
+                                <IconButton aria-label={labels.close} icon={<XIcon />} variant="header" />
+                            </NinnaDrawer.Close>
+                        </div>
+                    </div>
+                    {(subtitle ?? description) ? (
+                        <Text className="mt-2 wrap-break-word" variant="description" tone="muted">
+                            {subtitle ?? description}
+                        </Text>
+                    ) : null}
+                </header>
+                {children}
+            </NinnaDrawer.Content>
+        );
+    },
+);
+
+DrawerContent.displayName = 'Drawer.Content';
+
+const DrawerBody = forwardRef<HTMLDivElement, Omit<DrawerBodyProps, 'className'>>((props, ref) => (
+    <NinnaDrawer.Body
+        ref={ref}
+        {...props}
+        className="min-h-0 min-w-0 flex-1 overflow-y-auto overscroll-contain px-5 py-5 sm:px-6"
+    />
+));
+
+DrawerBody.displayName = 'Drawer.Body';
+
+const DrawerFooter = forwardRef<HTMLDivElement, Omit<DrawerFooterProps, 'className'>>((props, ref) => (
+    <NinnaDrawer.Footer
+        ref={ref}
+        {...props}
+        className="border-base-300 shrink-0 justify-between border-t px-5 py-3 sm:px-6 sm:py-3"
+    />
+));
+
+DrawerFooter.displayName = 'Drawer.Footer';
+
+export const Drawer = Object.assign(DrawerRoot, {
+    Body: DrawerBody,
+    Content: DrawerContent,
+    Footer: DrawerFooter,
+    Trigger: NinnaDrawer.Trigger,
+});

package/src/overlays/DropdownMenu.tsx

@@ -0,0 +1,122 @@
+/* oxlint-disable react/only-export-components -- Compound members are exported through DropdownMenu. */
+
+import {
+    DropdownMenu as NinnaDropdownMenu,
+    type DropdownMenuContentProps,
+    type DropdownMenuItemProps,
+    type DropdownMenuLabelProps,
+    type DropdownMenuRadioGroupProps,
+    type DropdownMenuRadioItemProps,
+} from '@ninna-ui/overlays';
+import { type ComponentProps, forwardRef } from 'react';
+
+interface DropdownMenuContentPolicyProps extends Omit<DropdownMenuContentProps, 'className'> {
+    width?: 'sm' | 'md';
+}
+
+const contentWidthClasses: Record<NonNullable<DropdownMenuContentPolicyProps['width']>, string> = {
+    sm: 'w-60',
+    md: 'w-64',
+};
+
+const DropdownMenuContent = forwardRef<HTMLDivElement, DropdownMenuContentPolicyProps>(
+    ({ side = 'bottom', sideOffset = 8, width = 'sm', ...props }, ref) => (
+        <NinnaDropdownMenu.Content
+            ref={ref}
+            side={side}
+            sideOffset={sideOffset}
+            {...props}
+            className={`${contentWidthClasses[width]} max-h-(--radix-dropdown-menu-content-available-height) max-w-[calc(100vw-2rem)] overflow-y-auto`}
+        />
+    ),
+);
+
+DropdownMenuContent.displayName = 'DropdownMenu.Content';
+
+interface DropdownMenuLabelPolicyProps extends Omit<DropdownMenuLabelProps, 'className'> {
+    presentation?: 'section' | 'identity';
+}
+
+const DropdownMenuLabel = forwardRef<HTMLDivElement, DropdownMenuLabelPolicyProps>(
+    ({ presentation = 'section', ...props }, ref) => (
+        <NinnaDropdownMenu.Label
+            ref={ref}
+            {...props}
+            className={presentation === 'identity' ? 'tracking-normal normal-case' : undefined}
+        />
+    ),
+);
+
+DropdownMenuLabel.displayName = 'DropdownMenu.Label';
+
+interface DropdownMenuItemPolicyProps extends Omit<DropdownMenuItemProps, 'className'> {
+    /** Forward the underlying menu item's behavior to a link without a second tab stop. */
+    asChild?: boolean;
+}
+
+const DropdownMenuItem = forwardRef<HTMLDivElement, DropdownMenuItemPolicyProps>((props, ref) => (
+    <NinnaDropdownMenu.Item
+        ref={ref}
+        {...props}
+        className="aria-[current=page]:bg-primary/10 aria-[current=page]:text-primary max-lg:min-h-11 pointer-coarse:min-h-11 [&>svg]:size-4 [&>svg]:shrink-0"
+    />
+));
+
+DropdownMenuItem.displayName = 'DropdownMenu.Item';
+
+interface DropdownMenuRadioGroupPolicyProps extends Omit<DropdownMenuRadioGroupProps, 'className'> {
+    presentation?: 'default' | 'segmented';
+}
+
+const DropdownMenuRadioGroup = forwardRef<HTMLDivElement, DropdownMenuRadioGroupPolicyProps>(
+    ({ presentation = 'default', ...props }, ref) => (
+        <NinnaDropdownMenu.RadioGroup
+            ref={ref}
+            {...props}
+            className={presentation === 'segmented' ? 'bg-base-200/70 flex gap-0.5 rounded-lg p-0.5' : undefined}
+        />
+    ),
+);
+
+DropdownMenuRadioGroup.displayName = 'DropdownMenu.RadioGroup';
+
+interface DropdownMenuRadioItemPolicyProps extends Omit<DropdownMenuRadioItemProps, 'className'> {
+    presentation?: 'default' | 'segmented';
+}
+
+const DropdownMenuRadioItem = forwardRef<HTMLDivElement, DropdownMenuRadioItemPolicyProps>(
+    ({ onSelect, presentation = 'default', ...props }, ref) => (
+        <NinnaDropdownMenu.RadioItem
+            ref={ref}
+            {...props}
+            data-presentation={presentation}
+            onSelect={
+                presentation === 'segmented'
+                    ? (event) => {
+                          event.preventDefault();
+                          onSelect?.(event);
+                      }
+                    : onSelect
+            }
+            className={
+                presentation === 'segmented'
+                    ? 'text-base-600 focus:bg-base-300 focus:text-base-content data-[state=checked]:bg-base-100 data-[state=checked]:text-base-content size-7 justify-center rounded-md p-0 data-[state=checked]:shadow-sm [&>span]:hidden [&>svg]:size-4'
+                    : 'max-lg:min-h-11 pointer-coarse:min-h-11 [&>svg]:size-4 [&>svg]:shrink-0'
+            }
+        />
+    ),
+);
+
+DropdownMenuRadioItem.displayName = 'DropdownMenu.RadioItem';
+
+function DropdownMenuRoot(props: ComponentProps<typeof NinnaDropdownMenu>) {
+    return <NinnaDropdownMenu {...props} />;
+}
+
+export const DropdownMenu = Object.assign(DropdownMenuRoot, NinnaDropdownMenu, {
+    Content: DropdownMenuContent,
+    Item: DropdownMenuItem,
+    Label: DropdownMenuLabel,
+    RadioGroup: DropdownMenuRadioGroup,
+    RadioItem: DropdownMenuRadioItem,
+});

package/src/overlays/ImageViewer.tsx

@@ -0,0 +1,96 @@
+import { Loading } from '@ninna-ui/feedback';
+import { Modal as NinnaModal } from '@ninna-ui/overlays';
+import { XIcon } from 'lucide-react';
+import { useId, useState } from 'react';
+
+import { IconButton } from '../actions/IconButton';
+import { useDesignSystemLabels } from '../foundations/DesignSystemProvider';
+import { Text } from '../typography/Typography';
+import { useModalAutoFocus } from './useModalAutoFocus';
+
+interface ImageViewerProps {
+    alt: string;
+    caption?: string;
+    onClose: () => void;
+    open: boolean;
+    /** Pixel size to show beside the caption; omit when unknown rather than guessing. */
+    resolution?: { height: number; width: number };
+    /** Omit while the image is not ready yet (still loading, authenticating, and so on); shows the
+     * same loading indicator as a slow-loading image rather than a broken one. */
+    src?: string;
+}
+
+/**
+ * Shows one image at its natural size over the blurred modal backdrop, scaled down only when it would not fit.
+ * Clicking anywhere except the image, the close button, or Escape dismisses it.
+ */
+export function ImageViewer({ alt, caption, onClose, open, resolution, src }: ImageViewerProps) {
+    const labels = useDesignSystemLabels();
+    const focusProps = useModalAutoFocus();
+    const captionId = useId();
+    const [loadedSource, setLoadedSource] = useState<string>();
+    const loaded = Boolean(src) && loadedSource === src;
+    const size = resolution ? labels.imageSize(resolution.width, resolution.height) : undefined;
+
+    return (
+        <NinnaModal open={open} onOpenChange={(next) => !next && onClose()}>
+            <NinnaModal.Content
+                {...focusProps}
+                title={caption ?? alt}
+                size="full"
+                className="top-0 left-0 flex h-dvh max-h-none w-screen translate-x-0 translate-y-0 items-center justify-center overflow-hidden rounded-none border-0 bg-transparent p-4 shadow-none sm:top-0 sm:left-0 sm:h-dvh sm:w-screen sm:translate-x-0 sm:translate-y-0 sm:p-8"
+                onClick={(event) => event.target === event.currentTarget && onClose()}
+            >
+                {/* The standard header close button, lightened because it always sits on the dark backdrop. */}
+                <div className="absolute top-5 right-5 z-10 [--color-header-icon:#ffffff] sm:top-6 sm:right-6">
+                    <NinnaModal.Close asChild>
+                        <IconButton aria-label={labels.close} icon={<XIcon />} variant="header" />
+                    </NinnaModal.Close>
+                </div>
+                {loaded ? null : (
+                    <span className="pointer-events-none absolute inset-0 flex items-center justify-center text-white/80">
+                        <Loading size="lg" />
+                    </span>
+                )}
+                {/* Only the image itself catches clicks; the space around it and the caption fall through to close. */}
+                <figure
+                    aria-labelledby={caption ? captionId : undefined}
+                    className="pointer-events-none m-0 flex max-w-full flex-col items-center gap-3"
+                >
+                    {src ? (
+                        <img
+                            alt={alt}
+                            src={src}
+                            decoding="async"
+                            ref={(image) => {
+                                if (image?.complete && image.naturalWidth > 0) setLoadedSource(src);
+                            }}
+                            onLoad={() => setLoadedSource(src)}
+                            onError={() => setLoadedSource(src)}
+                            className={`pointer-events-auto max-h-[calc(100dvh-7rem)] max-w-full rounded-lg object-contain shadow-2xl transition-opacity duration-200 motion-reduce:transition-none sm:max-h-[calc(100dvh-9rem)] ${loaded ? 'opacity-100' : 'opacity-0'}`}
+                        />
+                    ) : null}
+                    {caption || size ? (
+                        <figcaption className="flex max-w-prose flex-wrap items-baseline justify-center gap-x-3 gap-y-1 text-center">
+                            {caption ? (
+                                <Text
+                                    id={captionId}
+                                    as="span"
+                                    className="wrap-break-word text-white/90"
+                                    variant="label"
+                                >
+                                    {caption}
+                                </Text>
+                            ) : null}
+                            {size ? (
+                                <Text as="span" className="text-white/60 tabular-nums" variant="caption">
+                                    {size}
+                                </Text>
+                            ) : null}
+                        </figcaption>
+                    ) : null}
+                </figure>
+            </NinnaModal.Content>
+        </NinnaModal>
+    );
+}