@lar-works/design-system 0.2.1 → 0.3.0

package/src/feedback/StatusIndicator.tsx

@@ -4,6 +4,11 @@ interface StatusIndicatorProps {
     className?: string;
     size?: 'sm' | 'md';
     tone: StatusTone;
+    /** A colour that comes with data, such as a tracker label's own, in place of the tone's; none keeps the tone. */
+    labelColor?: string | undefined;
+    /** A short word after the dot in the tone's text colour, such as a check's "Installed"; the neutral tone mutes it,
+     *  for a check that didn't run. */
+    label?: string;
 }
 
 const toneClasses: Record<StatusTone, string> = {
@@ -14,15 +19,41 @@ const toneClasses: Record<StatusTone, string> = {
     info: 'bg-info',
 };
 
+const labelClasses: Record<StatusTone, string> = {
+    neutral: 'text-base-700',
+    success: 'text-(--lar-success-text)',
+    warning: 'text-(--lar-warning-text)',
+    danger: 'text-(--lar-danger-text)',
+    info: 'text-(--lar-info-text)',
+};
+
 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]
+export function StatusIndicator({ className, size = 'md', tone, labelColor, label }: StatusIndicatorProps) {
+    const classes = [
+        'inline-block shrink-0 rounded-full',
+        sizeClasses[size],
+        toneClasses[tone],
+        label ? null : className,
+    ]
         .filter(Boolean)
         .join(' ');
+    const dot = (
+        <span aria-hidden="true" className={classes} style={labelColor ? { background: labelColor } : undefined} />
+    );
+
+    if (label === undefined) return dot;
 
-    return <span aria-hidden="true" className={classes} />;
+    return (
+        <span
+            data-slot="status-indicator"
+            className={`inline-flex items-center gap-1.5 text-xs font-medium whitespace-nowrap ${labelClasses[tone]} ${className ?? ''}`}
+        >
+            {dot}
+            {label}
+        </span>
+    );
 }

package/src/feedback/index.ts

@@ -6,10 +6,20 @@ export {
     showErrorNotification,
     showSuccessNotification,
 } from './ErrorNotification';
-export { Notifications } from './Notifications';
+export { DismissButton } from './DismissButton';
+export { FormResult } from './FormResult';
+export { LiveRegion } from './LiveRegion';
+export {
+    clearNotification,
+    type Notification,
+    Notifications,
+    showNotification,
+    useNotificationControls,
+} from './Notifications';
+export { Progress } from './Progress';
 export { ProgressStatusRow } from './ProgressStatusRow';
 export { SkeletonLoader } from './SkeletonLoader';
+export { Loading } from './Loading';
 export { StatusIndicator, type StatusTone } from './StatusIndicator';
 export { StatusPopoverContent } from './StatusPopoverContent';
 export { StatusRow } from './StatusRow';
-export { Loading } from '@ninna-ui/feedback';

package/src/forms/ColorSwatches.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+
+export interface ColorSwatch {
+    /** What picking it sets, such as a hex colour without its #. */
+    value: string;
+    /** The CSS colour it shows. */
+    color: string;
+    /** Its accessible name, such as "Colour #D73A4A". */
+    label: string;
+}
+
+/**
+ * A row of round colour swatches, the one matching `value` (ignoring case) pressed and ringed, then `children`, such as
+ * a field for any other colour, wrapping when they don't fit.
+ */
+export function ColorSwatches({
+    swatches,
+    value,
+    disabled = false,
+    onPick,
+    children,
+}: {
+    swatches: readonly ColorSwatch[];
+    value: string;
+    disabled?: boolean;
+    onPick: (value: string) => void;
+    children?: ReactNode;
+}) {
+    return (
+        <span className="flex flex-wrap items-center gap-1.5">
+            {swatches.map((swatch) => {
+                const picked = swatch.value.toLowerCase() === value.toLowerCase();
+
+                return (
+                    <button
+                        key={swatch.value}
+                        type="button"
+                        aria-label={swatch.label}
+                        aria-pressed={picked}
+                        disabled={disabled}
+                        className={`size-5 rounded-full border ${picked ? 'ring-2 ring-(--primary) ring-offset-1 ring-offset-(--card)' : ''}`}
+                        style={{ background: swatch.color }}
+                        onClick={() => onPick(swatch.value)}
+                    />
+                );
+            })}
+            {children}
+        </span>
+    );
+}

package/src/forms/FormSection.tsx

@@ -1,13 +1,17 @@
 import { ChevronDownIcon } from 'lucide-react';
-import { type ReactNode, useId, useState } from 'react';
+import { type ComponentProps, type ReactNode, type SyntheticEvent, useId, useState } from 'react';
 
 import { Button, type ButtonProps } from '../actions/Button';
+import { Badge } from '../display/Badge';
 import { InsetPanel } from '../display/InsetPanel';
 import { SkeletonLoader } from '../feedback/SkeletonLoader';
 import { Stack } from '../layout/Flow';
+import { HelpTip } from '../overlays/HelpTip';
 import { Heading, Text } from '../typography/Typography';
 import { Field, type FieldProps } from './Field';
 
+type DataAttributes = { [key: `data-${string}`]: string | undefined };
+
 const contentSpacing = 'px-4 py-3.5 sm:px-5';
 const rowClasses = `grid min-w-0 gap-x-6 gap-y-3 sm:items-center ${contentSpacing}`;
 
@@ -30,10 +34,68 @@ interface FormSectionProps {
     description?: string;
     loading?: boolean;
     loadingLabel?: string;
+    presentation?: 'default';
     title: ReactNode;
 }
 
-export function FormSection({
+/** A dense tool's settings group: its title (with an optional help popover) and description over the content as
+ *  given, such as one or more settings panels and their notes. */
+interface DenseFormSectionProps extends DataAttributes {
+    presentation: 'dense';
+    title?: ReactNode;
+    /** Explains the group in a popover from a help button after the title; `helpLabel` names that button. */
+    help?: ReactNode;
+    helpLabel?: string;
+    description?: ReactNode;
+    /** Names the group when its title doesn't, or when it has none. */
+    'aria-label'?: string;
+    children?: ReactNode;
+}
+
+export function FormSection(props: FormSectionProps | DenseFormSectionProps) {
+    if (props.presentation === 'dense') return <DenseFormSection {...props} />;
+
+    return <PanelFormSection {...props} />;
+}
+
+function DenseFormSection({
+    presentation: _presentation,
+    title,
+    help,
+    helpLabel,
+    description,
+    'aria-label': label,
+    children,
+    ...data
+}: DenseFormSectionProps) {
+    const titleId = useId();
+
+    return (
+        <section
+            {...data}
+            aria-label={label}
+            aria-labelledby={label || !title ? undefined : titleId}
+            className="grid min-w-0 gap-3"
+        >
+            {(title || description) && (
+                <div>
+                    {title && (
+                        <h3 id={titleId} className="m-0 flex items-center gap-1.5 text-[13px] font-semibold">
+                            {title}
+                            {help && (
+                                <HelpTip label={helpLabel ?? (typeof title === 'string' ? title : '')}>{help}</HelpTip>
+                            )}
+                        </h3>
+                    )}
+                    {description && <p className="text-base-700 m-0 mt-0.5 text-xs">{description}</p>}
+                </div>
+            )}
+            {children}
+        </section>
+    );
+}
+
+function PanelFormSection({
     action,
     badges,
     children,
@@ -76,16 +138,40 @@ export function FormSection({
     );
 }
 
-interface FormRowProps {
+interface FormRowColumnsProps {
     badges?: ReactNode;
     children: ReactNode;
     description: string;
     /** The row's element id, for linking or scrolling to it; a row with one can take focus when it is opened. */
     id?: string;
     label: ReactNode;
+    layout?: 'columns';
+}
+
+/** A dense tool's settings row: the label (with an optional help popover) and description, then its controls flowing
+ *  beside them and wrapping under them when they don't fit, then content below and an error. */
+interface FormRowFlowProps extends DataAttributes {
+    layout: 'flow';
+    label: ReactNode;
+    /** Explains the setting in a popover from a help button after the label; `helpLabel` names that button. */
+    help?: ReactNode;
+    helpLabel?: string;
+    description?: ReactNode;
+    children?: ReactNode;
+    /** Full-width content under the label and controls, such as a list the setting governs. */
+    below?: ReactNode;
+    error?: string | undefined;
+    /** The error's element id, for a control's aria-describedby. */
+    errorId?: string;
 }
 
-export function FormRow({ badges, children, description, id, label }: FormRowProps) {
+type FormRowProps = FormRowColumnsProps | FormRowFlowProps;
+
+export function FormRow(props: FormRowProps) {
+    if (props.layout === 'flow') return <FormRowFlow {...props} />;
+
+    const { badges, children, description, id, label } = props;
+
     return (
         <div
             id={id}
@@ -108,6 +194,58 @@ export function FormRow({ badges, children, description, id, label }: FormRowPro
     );
 }
 
+function FormRowFlow({
+    layout: _layout,
+    label,
+    help,
+    helpLabel,
+    description,
+    children,
+    below,
+    error,
+    errorId,
+    ...data
+}: FormRowFlowProps) {
+    const fallbackErrorId = useId();
+
+    return (
+        <div {...data} className="settings-row grid min-w-0 gap-2 px-4 py-3">
+            <div className="flex min-w-0 flex-wrap items-center gap-x-6 gap-y-2">
+                <div className="min-w-32 flex-1">
+                    <div className="settings-row-title flex min-w-0 items-center gap-1.5 text-[13px] font-medium wrap-anywhere">
+                        {label}
+                        {help && (
+                            <HelpTip label={helpLabel ?? (typeof label === 'string' ? label : '')}>{help}</HelpTip>
+                        )}
+                    </div>
+                    {description && <div className="text-base-700 text-xs wrap-anywhere">{description}</div>}
+                </div>
+                {children && (
+                    <div className="settings-row-control flex max-w-full min-w-0 flex-wrap items-center gap-2 sm:max-w-[60%] [&_button]:max-w-full [&>span]:max-w-full">
+                        {children}
+                    </div>
+                )}
+            </div>
+            {below}
+            {error && (
+                <p id={errorId ?? fallbackErrorId} role="alert" className="m-0 text-xs text-(--lar-danger-text)">
+                    {error}
+                </p>
+            )}
+        </div>
+    );
+}
+
+/** A value and its unit beside it in a row's controls, such as a number field and "days". */
+export function FormUnit({ children, unit }: { children: ReactNode; unit: ReactNode }) {
+    return (
+        <span className="flex items-center gap-2 text-sm [&_input]:w-20">
+            {children}
+            {unit}
+        </span>
+    );
+}
+
 type FormFieldProps = Omit<FieldProps, 'children' | 'className'> & { action?: ReactNode } & (
         | { children: ReactNode; loading?: false; loadingLabel?: never }
         | { children?: never; loading: true; loadingLabel: string }
@@ -156,20 +294,117 @@ export function FormAction(props: Omit<ButtonProps, 'type' | 'size' | 'variant'
     return <Button {...props} type="button" variant="subtle" />;
 }
 
-export function Disclosure({ children, label, lazy = false }: { children: ReactNode; label: string; lazy?: boolean }) {
-    const [open, setOpen] = useState(false);
+export function Disclosure({
+    children,
+    label,
+    lazy = false,
+    presentation = 'note',
+    defaultOpen = false,
+    badge,
+    onOpenChange,
+    ...data
+}: {
+    children: ReactNode;
+    label: string;
+    lazy?: boolean;
+    /** `note` folds small muted text behind a chevron; `section` folds a section's own content, such as an earlier
+     *  version of a text, behind a muted label in the body size; `group` folds a form's optional group behind its
+     *  heading, such as optional settings; `framed` folds a short list in a frame, such as entries that can't be
+     *  picked. */
+    presentation?: 'note' | 'section' | 'group' | 'framed';
+    /** Starts open, such as a group whose kept answers may need a look. */
+    defaultOpen?: boolean;
+    /** A `group`'s badge after its heading, such as "Optional". */
+    badge?: string | undefined;
+    /** Hears each time it opens or closes, such as to read what it shows once it opens. */
+    onOpenChange?: (open: boolean) => void;
+} & DataAttributes) {
+    const [open, setOpen] = useState(defaultOpen);
+    const shown = !lazy || open ? children : null;
+    const toggle = (event: SyntheticEvent<HTMLDetailsElement>) => {
+        setOpen(event.currentTarget.open);
+        onOpenChange?.(event.currentTarget.open);
+    };
+
+    if (presentation === 'group')
+        return (
+            <details {...data} open={open} onToggle={toggle} className="min-w-0">
+                <summary className="cursor-pointer text-[13px] font-semibold">
+                    {label}
+                    {badge && (
+                        <>
+                            {' '}
+                            <Badge className="ms-1">{badge}</Badge>
+                        </>
+                    )}
+                </summary>
+                {shown && <div className="mt-3 grid min-w-0 gap-3">{shown}</div>}
+            </details>
+        );
+
+    if (presentation === 'framed')
+        return (
+            <details {...data} open={open} onToggle={toggle} className="min-w-0 rounded-lg border px-3 py-2">
+                <summary className="cursor-pointer text-sm font-medium">{label}</summary>
+                <div className="mt-2">{shown}</div>
+            </details>
+        );
+
+    if (presentation === 'section')
+        return (
+            <details {...data} className="grid min-w-0 gap-2" onToggle={toggle}>
+                <summary className="text-base-700 cursor-pointer text-sm">{label}</summary>
+                <div className="pt-2">{shown}</div>
+            </details>
+        );
 
     return (
-        <details className="group px-1" onToggle={(event) => setOpen(event.currentTarget.open)}>
+        <details {...data} className="group px-1" onToggle={toggle}>
             <summary className="text-base-700 hover:text-base-content focus-visible:outline-primary flex w-fit cursor-pointer list-none items-center gap-1.5 rounded py-1 text-xs focus-visible:outline-2 focus-visible:outline-offset-2 [&::-webkit-details-marker]:hidden">
                 <span aria-hidden="true" className="-rotate-90 transition-transform group-open:rotate-0 [&>svg]:size-3">
                     <ChevronDownIcon />
                 </span>
                 {label}
             </summary>
-            <div className="text-base-700 mt-2 space-y-2 text-xs leading-relaxed">
-                {!lazy || open ? children : null}
-            </div>
+            <div className="text-base-700 mt-2 space-y-2 text-xs leading-relaxed">{shown}</div>
         </details>
     );
 }
+
+type FormFieldsetProps = Omit<ComponentProps<'fieldset'>, 'style'> & {
+    /** The legend over the group. */
+    legend?: ReactNode;
+    /** Names the group for assistive technology only, where what's around it already says what it is. */
+    hiddenLegend?: boolean;
+    /** `group` only groups and disables its fields, with no frame. */
+    presentation?: 'bordered' | 'group';
+};
+
+/** The form section's fieldset: a bordered group of controls under a legend, on the native fieldset, which also
+ *  disables every control inside it. As a `group`, it only groups and disables its fields. */
+export function FormFieldset({
+    legend,
+    hiddenLegend = false,
+    presentation = 'bordered',
+    className = '',
+    children,
+    ...props
+}: FormFieldsetProps) {
+    return (
+        <fieldset
+            className={`m-0 min-w-0 ${presentation === 'group' ? 'border-0 p-0' : 'border-base-300 mb-3 rounded-lg border px-3 pt-2 pb-0 [&>legend]:mb-2 [&>legend]:font-semibold'} ${className}`}
+            data-slot="fieldset"
+            {...props}
+        >
+            {legend ? (
+                <legend
+                    className={hiddenLegend ? 'sr-only' : 'text-base-content p-0 text-sm leading-5 font-medium'}
+                    data-slot="fieldset-legend"
+                >
+                    {legend}
+                </legend>
+            ) : null}
+            {children}
+        </fieldset>
+    );
+}

package/src/forms/HiddenField.tsx

@@ -0,0 +1,4 @@
+/** A value a form submits that nobody edits in place, such as a pick made in a popover: a hidden field. */
+export function HiddenField({ name, value }: { name: string; value: string }) {
+    return <input type="hidden" name={name} value={value} />;
+}

package/src/forms/Input.tsx

@@ -3,18 +3,40 @@ import { forwardRef } from 'react';
 
 import { formControlClasses, formControlDefaults } from './FormControlStyles';
 
-export type InputProps = Omit<NinnaInputProps, 'fullWidth'>;
+export type InputProps = Omit<NinnaInputProps, 'fullWidth'> & {
+    /** A `field` fills its container; `setting` is a settings row's 16rem text field, narrower where the row is; `short`
+     *  holds a few characters, such as a hex colour; `count` a small whole number; `title` is a document's title typed
+     *  in place, borderless in large semibold type, such as a new item's. */
+    presentation?: 'field' | 'setting' | 'short' | 'count' | 'title';
+};
+
+const presentations = {
+    field: '',
+    setting: 'w-64 max-w-full',
+    short: 'w-24',
+    count: 'w-20',
+    title: 'text-base-content w-full shrink-0 border-0 bg-transparent p-0 text-xl font-semibold tracking-tight outline-none placeholder:font-medium placeholder:text-(--muted-foreground)',
+} as const;
 
 export const Input = forwardRef<HTMLInputElement, InputProps>(
-    ({ size = formControlDefaults.size, variant = formControlDefaults.variant, className, ...props }, ref) => (
+    (
+        {
+            size = formControlDefaults.size,
+            variant = formControlDefaults.variant,
+            presentation = 'field',
+            className,
+            ...props
+        },
+        ref,
+    ) => (
         <NinnaInput
             ref={ref}
             color={formControlDefaults.color}
             {...props}
             fullWidth
             size={size}
-            variant={variant}
-            className={`${variant === 'filled' ? formControlClasses : ''} ${className ?? ''}`}
+            variant={presentation === 'title' ? 'unstyled' : variant}
+            className={`${variant === 'filled' && presentation !== 'title' ? formControlClasses : ''} ${presentations[presentation]} ${className ?? ''}`}
         />
     ),
 );

package/src/forms/LabelPicker.tsx

@@ -0,0 +1,140 @@
+import { PlusIcon } from 'lucide-react';
+import { useState } from 'react';
+
+import { Button } from '../actions/Button';
+import { StatusIndicator } from '../feedback/StatusIndicator';
+import { Checkbox } from './Checkbox';
+import { Input } from './Input';
+
+export interface LabelChoice {
+    name: string;
+    /** A CSS colour; a tracker with no label colours gives none. */
+    color?: string | undefined;
+    description?: string | undefined;
+}
+
+/** Lets a typed name no choice has become a new label. */
+export interface LabelCreation {
+    /** Why this person can't add new labels at all, or null when they can. */
+    refused: string | null;
+    /** Why this name can't be a label, or null when it can. */
+    problem: (name: string) => string | null;
+    /** What adding one does, under the list. */
+    note: string;
+    /** The button that adds `name`, such as `Create "name"`. */
+    createLabel: (name: string) => string;
+    onCreate: (name: string) => void;
+}
+
+interface LabelPickerProps {
+    choices: readonly LabelChoice[];
+    picked: readonly string[];
+    onToggle: (name: string) => void;
+    /** The filter field's accessible name and its placeholder. */
+    filterLabel: string;
+    placeholder: string;
+    /** Shown when the filter matches nothing. */
+    noMatchLabel: string;
+    /** Choices shown ticked or not but not changeable here, each marked with `lockedNote`. */
+    locked?: readonly string[];
+    lockedNote?: string;
+    busy?: boolean;
+    create?: LabelCreation;
+    /** Whether two names are the same label; trackers compare them ignoring case. */
+    same?: (a: string, b: string) => boolean;
+}
+
+const ignoringCase = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
+
+/**
+ * A searchable checklist of labels, with each label's colour and description. It holds only its search text: the
+ * caller gives the choices, what is picked and what a toggle does, so it reads and writes whichever way its surface
+ * needs. With `create`, Enter or the create button lets a typed name no choice has in.
+ */
+export function LabelPicker({
+    choices,
+    picked,
+    onToggle,
+    filterLabel,
+    placeholder,
+    noMatchLabel,
+    locked = [],
+    lockedNote,
+    busy = false,
+    create,
+    same = ignoringCase,
+}: LabelPickerProps) {
+    const [query, setQuery] = useState('');
+    const typed = query.trim();
+    const hits = choices.filter(({ name }) => name.toLowerCase().includes(typed.toLowerCase()));
+    const fresh = !!create && !!typed && !choices.some(({ name }) => same(name, typed));
+    const refusal = fresh ? (create.refused ?? create.problem(typed)) : null;
+    const add = () => {
+        create?.onCreate(typed);
+        setQuery('');
+    };
+
+    return (
+        <div className="grid w-72 gap-2" data-label-picker aria-busy={busy}>
+            <Input
+                autoFocus
+                placeholder={placeholder}
+                aria-label={filterLabel}
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+                onKeyDown={(e) => {
+                    if (e.key !== 'Enter') return;
+
+                    e.preventDefault();
+
+                    if (fresh && !refusal) add();
+                }}
+            />
+            <div className="grid max-h-56 gap-0.5 overflow-y-auto">
+                {hits.map(({ name, color, description }) => {
+                    const fixed = locked.some((label) => same(label, name));
+
+                    return (
+                        <label
+                            key={name}
+                            data-label-choice
+                            className="hover:bg-base-200 flex cursor-pointer items-start gap-2 rounded-md px-1.5 py-1 text-xs"
+                        >
+                            <Checkbox
+                                checked={picked.some((label) => same(label, name))}
+                                disabled={fixed}
+                                onChange={() => onToggle(name)}
+                            />
+                            {color && (
+                                <span data-label-dot className="mt-1 flex">
+                                    <StatusIndicator tone="neutral" labelColor={color} />
+                                </span>
+                            )}
+                            <span className="min-w-0 flex-1">
+                                <span className="block wrap-anywhere">
+                                    {name}
+                                    {fixed && lockedNote && <span className="text-base-700"> · {lockedNote}</span>}
+                                </span>
+                                {description && <span className="text-base-700 block text-[11px]">{description}</span>}
+                            </span>
+                        </label>
+                    );
+                })}
+                {!hits.length && !fresh && <p className="text-base-700 m-0 p-1.5 text-[11px]">{noMatchLabel}</p>}
+            </div>
+            {fresh && !refusal && (
+                <span className="justify-self-start">
+                    <Button variant="secondary" compact leftIcon={<PlusIcon />} onClick={add}>
+                        {create.createLabel(typed)}
+                    </Button>
+                </span>
+            )}
+            {refusal && (
+                <p role="alert" className="text-base-700 m-0 text-[11px]">
+                    {refusal}
+                </p>
+            )}
+            {create && !create.refused && <p className="text-base-700 m-0 text-[11px]">{create.note}</p>}
+        </div>
+    );
+}