@lar-works/design-system 0.2.1 → 0.3.0

package/src/forms/OptionSelect.tsx

@@ -1,14 +1,45 @@
+import { type KeyboardEvent, type ReactNode, type Ref, useRef } from 'react';
+import { flushSync } from 'react-dom';
+
 import { SkeletonLoader } from '../feedback/SkeletonLoader';
-import { Select, SelectItem } from './Select';
+import { Select, SelectItem, type SelectProps } from './Select';
 
-interface LoadedOptionSelectProps<Value extends string> {
-    disabled?: boolean;
+const NONE = '__none';
+
+export interface OptionSelectOption<Value extends string = string> {
     label: string;
+    value: Value;
+    /** Disabled options stay visible but cannot be chosen. */
+    disabled?: boolean;
+    icon?: ReactNode;
+    /** A lar-brand app hue that colours the icon, such as a kind's. */
+    hue?: number;
+}
+
+interface LoadedOptionSelectProps<Value extends string> extends Omit<
+    SelectProps,
+    'value' | 'defaultValue' | 'onValueChange' | 'onChange' | 'children' | 'className' | 'size' | 'variant'
+> {
+    /** The select's accessible name; leave it out when a label names the select by its `id`. */
+    label?: string;
     loading?: false;
     onChange: (value: Value) => void;
-    /** Disabled options stay visible but cannot be chosen. */
-    options: readonly { label: string; value: Value; disabled?: boolean }[];
-    value: Value;
+    options: readonly OptionSelectOption<Value>[];
+    /** An empty value shows the placeholder, or `none`. */
+    value: Value | '';
+    /** The name of the option that empties the value, which `onChange` hears as ''. */
+    none?: string;
+    /** A form field's name: the select gives its form the value in a hidden field, and fires input on that field once
+     *  a pick has rendered, as Select is a button over a listbox that fires no input event of its own. */
+    name?: string;
+    /** A pick writes at once, so a letter key on the closed control doesn't pick: the Select's typeahead only works
+     *  once its list is open. */
+    writesOnPick?: boolean;
+    /** Busy rather than disabled while a pick it made saves: it keeps the focus and ignores picks. */
+    busy?: boolean;
+    /** `setting` is a settings row's 11rem dropdown; a `field` fills its container. */
+    presentation?: 'field' | 'setting';
+    ref?: Ref<HTMLButtonElement>;
 }
 
 interface LoadingOptionSelectProps {
@@ -18,7 +49,17 @@ interface LoadingOptionSelectProps {
 
 type OptionSelectProps<Value extends string> = LoadedOptionSelectProps<Value> | LoadingOptionSelectProps;
 
+/** Marks a letter key as handled, which the Select's trigger takes as leaving its typeahead out. Space and arrows still
+ *  open the list. */
+const withoutClosedTypeahead = (event: KeyboardEvent) => {
+    if (event.key.length === 1 && event.key !== ' ' && !event.ctrlKey && !event.altKey && !event.metaKey)
+        event.preventDefault();
+};
+
+/** A Select over plain options, each with an optional icon; while they load, a control-shaped skeleton. */
 export function OptionSelect<Value extends string>(props: OptionSelectProps<Value>) {
+    const field = useRef<HTMLInputElement>(null);
+
     if (props.loading)
         return (
             <SkeletonLoader label={props.label}>
@@ -26,24 +67,68 @@ export function OptionSelect<Value extends string>(props: OptionSelectProps<Valu
             </SkeletonLoader>
         );
 
-    const { disabled, label, onChange, options, value } = props;
-
-    return (
-        <Select
-            aria-label={label}
-            disabled={disabled}
-            value={value}
-            onValueChange={(next) => {
-                const option = options.find((candidate) => candidate.value === next);
-
-                if (option) onChange(option.value);
-            }}
-        >
-            {options.map((option) => (
-                <SelectItem key={option.value} value={option.value} disabled={option.disabled}>
-                    {option.label}
-                </SelectItem>
-            ))}
-        </Select>
+    const {
+        label,
+        loading: _loading,
+        onChange,
+        options,
+        value,
+        none,
+        name,
+        writesOnPick,
+        busy = false,
+        presentation = 'field',
+        ...select
+    } = props;
+    const pick = (next: string) => {
+        if (busy) return;
+
+        if (none && next === NONE) {
+            change(() => onChange('' as Value));
+
+            return;
+        }
+
+        const option = options.find((candidate) => candidate.value === next);
+
+        if (option) change(() => onChange(option.value));
+    };
+    const change = (write: () => void) => {
+        if (!name) return write();
+
+        flushSync(write);
+        field.current?.dispatchEvent(new Event('input', { bubbles: true }));
+    };
+
+    const control = (
+        <>
+            {name && <input ref={field} type="hidden" name={name} value={value} />}
+            <Select
+                {...select}
+                {...(label !== undefined && { 'aria-label': label })}
+                {...(writesOnPick && { onKeyDown: withoutClosedTypeahead })}
+                {...(busy && { 'aria-disabled': true })}
+                value={value || (none ? NONE : '')}
+                onValueChange={pick}
+            >
+                {none && <SelectItem value={NONE}>{none}</SelectItem>}
+                {options.map((option) => (
+                    <SelectItem
+                        key={option.value}
+                        value={option.value}
+                        disabled={option.disabled}
+                        {...(option.icon !== undefined && {
+                            icon: option.icon,
+                            iconHue: option.hue,
+                            textValue: option.label,
+                        })}
+                    >
+                        {option.label}
+                    </SelectItem>
+                ))}
+            </Select>
+        </>
     );
+
+    return presentation === 'setting' ? <span className="block w-44 max-w-full">{control}</span> : control;
 }

package/src/forms/Select.tsx

@@ -28,19 +28,26 @@ export const Select = forwardRef<HTMLButtonElement, SelectProps>(
 
 Select.displayName = 'Select';
 
-export const SelectItem = forwardRef<HTMLDivElement, SelectItemProps>(({ icon, children, ...props }, ref) => (
-    <NinnaSelectItem ref={ref} {...props}>
-        {icon ? (
-            <span className="inline-flex min-w-0 items-center gap-2 align-middle">
-                <span aria-hidden="true" className="size-4 shrink-0 [&>svg]:size-full">
-                    {icon}
+/** An option of the Select; its `icon` takes `iconHue`, a lar-brand app hue at full strength, when given. */
+export const SelectItem = forwardRef<HTMLDivElement, SelectItemProps & { iconHue?: number | undefined }>(
+    ({ icon, iconHue, children, ...props }, ref) => (
+        <NinnaSelectItem ref={ref} {...props}>
+            {icon ? (
+                <span className="inline-flex min-w-0 items-center gap-2 align-middle">
+                    <span
+                        aria-hidden="true"
+                        className="size-4 shrink-0 [&>svg]:size-full"
+                        style={iconHue === undefined ? undefined : { color: `oklch(0.62 0.15 ${iconHue})` }}
+                    >
+                        {icon}
+                    </span>
+                    <span className="truncate">{children}</span>
                 </span>
-                <span className="truncate">{children}</span>
-            </span>
-        ) : (
-            children
-        )}
-    </NinnaSelectItem>
-));
+            ) : (
+                children
+            )}
+        </NinnaSelectItem>
+    ),
+);
 
 SelectItem.displayName = 'SelectItem';

package/src/forms/Switch.tsx

@@ -3,8 +3,22 @@ import { forwardRef } from 'react';
 
 import { tabbable } from '../foundations/KeyboardFocus';
 
-export const Switch = forwardRef<HTMLButtonElement, SwitchProps>((props, ref) => (
-    <NinnaSwitch ref={ref} {...tabbable} size="sm" aria-busy={props.loading || undefined} {...props} />
+type Props = SwitchProps & {
+    /** Busy rather than disabled while a change it started saves: it keeps the focus and ignores presses. */
+    busy?: boolean;
+};
+
+export const Switch = forwardRef<HTMLButtonElement, Props>(({ busy = false, onCheckedChange, ...props }, ref) => (
+    <NinnaSwitch
+        ref={ref}
+        {...tabbable}
+        size="sm"
+        aria-busy={props.loading || undefined}
+        {...props}
+        {...(busy && { 'aria-disabled': true })}
+        className={`aria-disabled:cursor-progress ${props.className ?? ''}`}
+        onCheckedChange={(checked) => !busy && onCheckedChange?.(checked)}
+    />
 ));
 
 Switch.displayName = 'Switch';

package/src/forms/index.ts

@@ -1,9 +1,23 @@
 export { Checkbox, type CheckboxProps } from './Checkbox';
+export { type ColorSwatch, ColorSwatches } from './ColorSwatches';
 export { Field, type FieldProps } from './Field';
-export { Disclosure, FormAction, FormContent, FormField, FormRow, FormSection, FormStack } from './FormSection';
+export {
+    Disclosure,
+    FormAction,
+    FormContent,
+    FormField,
+    FormFieldset,
+    FormRow,
+    FormSection,
+    FormStack,
+    FormUnit,
+} from './FormSection';
+export { HiddenField } from './HiddenField';
 export { InlineFields } from './InlineFields';
 export { Input, type InputProps } from './Input';
-export { OptionSelect } from './OptionSelect';
+export { type LabelChoice, type LabelCreation, LabelPicker } from './LabelPicker';
+export { MarkdownEditor } from './MarkdownEditor';
+export { OptionSelect, type OptionSelectOption } from './OptionSelect';
 export { RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps } from './RadioGroup';
 export { Select, SelectItem, type SelectProps } from './Select';
 export { Switch } from './Switch';

package/src/foundations/AmbientMotion.ts

@@ -0,0 +1,51 @@
+// One observer for a page's repeating indicators (spinners, pulses, sweeps). Each keeps its phase while outside a
+// scroll viewport or while the window is hidden; resuming never changes the status or restarts the animation. Use it
+// as a ref callback: React 19 runs the returned cleanup when the ref detaches, including its StrictMode check.
+// theme.css pauses an element marked data-ambient-motion="paused".
+
+const indicators = new Map<Element, boolean>();
+let observer: IntersectionObserver | undefined;
+
+function update(element: Element, visible: boolean): void {
+    element.setAttribute('data-ambient-motion', visible && !document.hidden ? 'running' : 'paused');
+}
+
+function visibilityChanged(): void {
+    for (const [element, visible] of indicators) update(element, visible);
+}
+
+export function ambientMotion(element: Element | null): (() => void) | undefined {
+    if (!element) return;
+
+    if (!indicators.size) document.addEventListener('visibilitychange', visibilityChanged);
+
+    // Without IntersectionObserver, visibility changes still pause indicators in a hidden window.
+    const visible = typeof IntersectionObserver === 'undefined';
+
+    indicators.set(element, visible);
+    update(element, visible);
+
+    if (!visible) {
+        observer ??= new IntersectionObserver((entries) => {
+            for (const { target, isIntersecting } of entries) {
+                if (!indicators.has(target)) continue;
+
+                indicators.set(target, isIntersecting);
+                update(target, isIntersecting);
+            }
+        });
+        observer.observe(element);
+    }
+
+    return () => {
+        observer?.unobserve(element);
+        indicators.delete(element);
+        element.removeAttribute('data-ambient-motion');
+
+        if (!indicators.size) {
+            observer?.disconnect();
+            observer = undefined;
+            document.removeEventListener('visibilitychange', visibilityChanged);
+        }
+    };
+}

package/src/foundations/DesignSystemProvider.tsx

@@ -29,6 +29,23 @@ export const defaultDesignSystemLabels = {
         light: 'Light',
         dark: 'Dark',
     },
+    editor: {
+        formatting: 'Formatting',
+        bold: 'Bold',
+        italic: 'Italic',
+        heading: 'Heading',
+        bulletedList: 'Bulleted list',
+        numberedList: 'Numbered list',
+        link: 'Link',
+        linkUrl: 'Link URL',
+        linkPlaceholder: 'https://…',
+        apply: 'Apply',
+        markdown: 'Markdown',
+    },
+    dialog: {
+        expand: 'Expand',
+        restoreSize: 'Restore size',
+    },
 };
 
 export type DesignSystemLabels = typeof defaultDesignSystemLabels;
@@ -71,6 +88,8 @@ function mergeLabels(labels: DesignSystemLabelOverrides | undefined): DesignSyst
         ...labels,
         folders: { ...defaultDesignSystemLabels.folders, ...labels.folders },
         theme: { ...defaultDesignSystemLabels.theme, ...labels.theme },
+        editor: { ...defaultDesignSystemLabels.editor, ...labels.editor },
+        dialog: { ...defaultDesignSystemLabels.dialog, ...labels.dialog },
     };
 }
 

package/src/foundations/index.ts

@@ -5,6 +5,7 @@ export {
     DesignSystemProvider,
     useDesignSystemLabels,
 } from './DesignSystemProvider';
+export { ambientMotion } from './AmbientMotion';
 export { tabbable } from './KeyboardFocus';
 export { applePlatform, isShortcut } from './KeyboardShortcut';
 export { createThemeController, isThemePreference, type ThemeController, type ThemePreference } from './Theme';

package/src/foundations/theme.css

@@ -334,6 +334,64 @@ body {
     background: var(--color-base-300);
 }
 
+/* Notifications' stack presentation: every notification, oldest above the newest, in the bottom right corner with the
+   same gap from the window's bottom and right edges, and from the title bar (h-13) when it's full, above every dialog
+   (z-50) and full-screen cover (z-60). Each carries its slice of the stack's edge fade (Notifications.tsx), off while
+   one has keyboard focus, as in a Modal's body. Successes and failures are tinted. */
+.notification-stack {
+    --notice-edge: calc(var(--spacing) * 4);
+    right: var(--notice-edge);
+    bottom: var(--notice-edge);
+    z-index: 100;
+    flex-direction: column;
+    width: min(calc(var(--spacing) * 104), calc(100vw - var(--spacing) * 8));
+    max-width: none;
+    max-height: calc(100dvh - var(--spacing) * 13 - var(--notice-edge) * 2);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    pointer-events: auto;
+    -webkit-app-region: no-drag;
+}
+
+.notification-stack:empty {
+    pointer-events: none;
+}
+
+.notification-stack [data-slot='toast'] {
+    flex-shrink: 0;
+    overflow-wrap: anywhere;
+}
+
+.notification-stack > [data-slot='toast'] {
+    mask-image: linear-gradient(
+        to bottom,
+        transparent var(--fade-from, 0%),
+        black var(--fade-top, 0%),
+        black var(--fade-bottom, 100%),
+        transparent var(--fade-to, 100%)
+    );
+}
+
+.notification-stack:has(:focus-visible) > [data-slot='toast'] {
+    mask-image: none;
+}
+
+.notification-stack [data-slot='content'] {
+    min-width: 0;
+}
+
+.notification-stack [data-slot='toast'][data-toast-color='warning'] {
+    @apply bg-warning/10 border-warning/20 text-(--lar-warning-text);
+}
+
+.notification-stack [data-slot='toast'][data-toast-color='success'] {
+    @apply bg-success/10 border-success/20 text-(--lar-success-text);
+}
+
+.notification-stack [data-slot='toast'][data-toast-color='danger'] {
+    @apply bg-danger/10 border-danger/20 text-(--lar-danger-text);
+}
+
 [data-slot='tooltip-content'] {
     @apply glass-menu;
     max-width: min(var(--radix-tooltip-content-available-width), var(--container-xs));
@@ -398,6 +456,12 @@ body {
     }
 }
 
+/* A repeating indicator that ambientMotion (AmbientMotion.ts) finds out of view or in a hidden window. Dialogs,
+   loading entrances and interaction transitions keep their timing, as only repeating indicators opt in. */
+[data-ambient-motion='paused'] {
+    animation-play-state: paused;
+}
+
 .lar-progress-indeterminate {
     width: 35%;
     animation: lar-progress-travel 1.8s ease-in-out infinite alternate;

package/src/icons/BrandIcons.tsx

@@ -1,8 +1,17 @@
-/** Brand marks, which lucide does not draw. */
-export function GitHubIcon() {
+/** Brand marks, which lucide does not draw. Each takes a `className` for its size, as a lucide icon does. */
+export function GitHubIcon({ className }: { className?: string }) {
     return (
-        <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+        <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true" className={className}>
             <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8Z" />
         </svg>
     );
 }
+
+/** Azure DevOps' mark. */
+export function AzureDevOpsIcon({ className }: { className?: string }) {
+    return (
+        <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" className={className}>
+            <path d="M0 8.899l2.247-2.966 8.405-3.416V.045l7.37 5.393L2.966 8.36v8.2L0 15.685zm24-4.45v14.652L18.247 24l-9.303-3.237v3.237l-5.978-7.44 15.056 1.79V5.438z" />
+        </svg>
+    );
+}

package/src/icons/dynamic.ts

@@ -0,0 +1,4 @@
+// lucide's DynamicIcon, which draws an icon by its kebab-case name, such as one a person chose in another app. Its name
+// map and each icon are lazy chunks, so this has an entry of its own (`@lar-works/design-system/icons/dynamic`), which
+// apps load with a dynamic import where they need it.
+export { DynamicIcon, type IconName } from 'lucide-react/dynamic';

package/src/icons/index.ts

@@ -1,4 +1,4 @@
 // Every icon comes from lucide (https://lucide.dev/icons), under lucide's `…Icon` names, plus the brand marks
 // lucide does not draw. Apps import icons from `@lar-works/design-system/icons`, never from lucide-react.
-export { GitHubIcon } from './BrandIcons';
+export { AzureDevOpsIcon, GitHubIcon } from './BrandIcons';
 export * from 'lucide-react';

package/src/index.ts

@@ -1,6 +1,7 @@
 // The design system's public API. Icons have their own entry (`@lar-works/design-system/icons`), and styles are
-// imported once by each app (`@import '@lar-works/design-system/styles.css'`).
+// imported once by each app (`@import '@lar-works/design-system/styles.css'`, or showcase.css or board.css).
 export * from './actions';
+export * from './board';
 export * from './collections';
 export * from './display';
 export * from './feedback';

package/src/layout/index.ts

@@ -7,7 +7,7 @@ export { Section } from './Section';
 export { SidebarNavigationItem } from './sidebar/SidebarNavigationItem';
 export { SidebarNavigationGroup, SidebarPane } from './sidebar/SidebarPane';
 export { TitleBar, TitleBarTrail, type TitleBarTrailItem } from './TitleBar';
-export { CommandPaletteTrigger } from './toolbar/CommandPaletteTrigger';
+export { CommandPaletteTrigger, type CommandPaletteTriggerToken } from './toolbar/CommandPaletteTrigger';
 export { ToolbarStatusGroup } from './toolbar/ToolbarStatusGroup';
 export { ToolbarStatusItem } from './toolbar/ToolbarStatusItem';
 export { WorkspaceActionsHeader } from './WorkspaceActionsHeader';