@lar-works/design-system 0.2.0 → 0.3.0

package/src/board/ItemParts.tsx

@@ -0,0 +1,128 @@
+// The bits every view of Lar Factory's board draws for a piece of work: its numbered title, title link, repository,
+// tracker fields, kind marker, label chips and planning notes.
+
+import { ArrowLeftRightIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { Badge } from '../display/Badge';
+import type { DataAttributes } from './DataAttributes';
+
+/** A title with its ticket's reference (`#12`) before it, muted, the way the board lists every item; captured work has
+ *  no reference. */
+export function ItemTitle({ reference, title }: { reference?: string | undefined; title: string }) {
+    return (
+        <>
+            {reference ? (
+                <>
+                    <span className="font-normal text-(--muted-foreground) tabular-nums">{reference}</span>{' '}
+                </>
+            ) : null}
+            {title}
+        </>
+    );
+}
+
+/** A title with its reference as a link to its ticket in a new tab, or as text when it has no page, as a sentence names
+ *  it. */
+export function TitleLink({
+    reference,
+    title,
+    href,
+}: {
+    reference?: string | undefined;
+    title: string;
+    href?: string | undefined;
+}) {
+    const text = (
+        <>
+            {reference ? (
+                <>
+                    <span className="ref">{reference}</span>{' '}
+                </>
+            ) : null}
+            {title}
+        </>
+    );
+
+    return href ? (
+        <a className="title" href={href} target="_blank" rel="noopener">
+            {text}
+        </a>
+    ) : (
+        <span className="title">{text}</span>
+    );
+}
+
+/** A repository as a badge: its project icon and name. */
+export function RepoTag({ icon, name }: { icon: ReactNode; name: string }) {
+    return (
+        <Badge className="gap-1.5">
+            {icon}
+            {name}
+        </Badge>
+    );
+}
+
+const identities = {
+    row: 'flex min-w-0 items-center gap-1',
+    map: 'inline-flex min-w-0 items-center gap-1.5',
+    wrap: 'inline-flex min-w-0 items-center gap-2',
+} as const;
+
+/** A repository's project icon and name together, the name truncating: in a row's line, or roomier on the work map,
+ *  where `title` names it in full. `wrap` is roomier still and wraps the name, anywhere if it must, for a line that
+ *  says more than the name, such as an archived item's repository, number and state. */
+export function RepoIdentity({
+    icon,
+    name,
+    title,
+    presentation = 'row',
+    ...data
+}: {
+    icon: ReactNode;
+    name: string;
+    title?: string;
+    presentation?: 'row' | 'map' | 'wrap';
+} & DataAttributes) {
+    return (
+        <span {...data} title={title} className={identities[presentation]}>
+            {icon}
+            <span className={presentation === 'wrap' ? 'min-w-0 wrap-anywhere' : 'truncate'}>{name}</span>
+        </span>
+    );
+}
+
+/** A tracker's fields for the item (such as Azure's type, state and assignee) as one muted line that truncates, its
+ *  tooltip giving it whole. */
+export function ItemFields({ text, ...data }: { text: string } & DataAttributes) {
+    return (
+        <span {...data} title={text} className="block min-w-0 truncate text-xs text-(--muted-foreground)">
+            {text}
+        </span>
+    );
+}
+
+/** Beside a kind badge, in muted text: the kind the ticket says instead, `said`, until someone answers. */
+export function KindMarker({
+    said,
+    label,
+    title,
+    ...data
+}: {
+    said: string;
+    /** The sentence assistive technology reads. */
+    label: string;
+    title: string;
+} & DataAttributes) {
+    return (
+        <span
+            {...data}
+            title={title}
+            aria-label={label}
+            className="inline-flex items-center gap-0.5 text-[11px] text-(--muted-foreground)"
+        >
+            <ArrowLeftRightIcon className="size-2.5" aria-hidden="true" />
+            {said}
+        </span>
+    );
+}

package/src/board/ItemProgress.tsx

@@ -0,0 +1,164 @@
+// The progress at the top of Lar Factory's item dialog: the workflow's steps as a bar, a concept's parts done, and a
+// piece of work's slices as chips under their count.
+
+import type { ReactNode } from 'react';
+
+import type { DataAttributes } from './DataAttributes';
+import type { SliceProgress } from './Slices';
+import { SliceMark } from './Slices';
+
+const PAST = 'color-mix(in srgb, var(--foreground) 28%, transparent)';
+
+/** The dialog's progress block: the steps, the parts, the activity and the slices, stacked. */
+export function ItemProgressPanel({ children, ...data }: { children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className="grid min-w-0 grid-cols-[minmax(0,1fr)] gap-2">
+            {children}
+        </div>
+    );
+}
+
+/** A count's line over its bar, such as "Slices · 2/3 done": `label` in the text colour, then `children`. */
+export function ProgressCount({ label, children }: { label: string; children: ReactNode }) {
+    return (
+        <p className="m-0 text-xs text-(--muted-foreground)">
+            <span className="font-medium text-(--foreground)">{label}</span> · {children}
+        </p>
+    );
+}
+
+/**
+ * The workflow's active steps as a bar: the past ones slim and darker, the upcoming faint, and the current one widest,
+ * named `name` with its step number, in a gradient of `color`, or `bar` (such as its slices) in that gradient's place.
+ * Each step's `label` is what assistive technology reads and its `title` its tooltip.
+ */
+export function WorkflowSteps({
+    steps,
+    at,
+    name,
+    color,
+    bar,
+}: {
+    steps: readonly { title: string; label: string }[];
+    /** The current step's index. */
+    at: number;
+    name: string;
+    color: string;
+    bar?: ReactNode;
+}) {
+    return (
+        <ol className="m-0 flex list-none items-end gap-[3px] p-0" data-steps>
+            {steps.map((step, i) =>
+                i !== at ? (
+                    <li
+                        key={i}
+                        title={step.title}
+                        aria-label={step.label}
+                        className="h-1.5 min-w-1.5 flex-1 rounded-full"
+                        style={{ background: i < at ? PAST : 'var(--soft)' }}
+                    />
+                ) : (
+                    <li
+                        key={i}
+                        title={step.title}
+                        aria-label={step.label}
+                        aria-current="step"
+                        className="grid min-w-26 flex-[6] gap-1"
+                    >
+                        <span className="flex items-baseline justify-between gap-2 text-xs leading-4">
+                            <span className="truncate font-medium">{name}</span>
+                            <span className="shrink-0 text-(--muted-foreground) tabular-nums">
+                                {i + 1}/{steps.length}
+                            </span>
+                        </span>
+                        {bar ? (
+                            <div aria-hidden>{bar}</div>
+                        ) : (
+                            <span
+                                className="h-1.5 rounded-full"
+                                style={{
+                                    background: `linear-gradient(90deg, color-mix(in srgb, ${color} 55%, transparent), ${color})`,
+                                }}
+                            />
+                        )}
+                    </li>
+                ),
+            )}
+        </ol>
+    );
+}
+
+/** A concept's parts done out of its parts, as a ProgressCount over a bar in the done colour. */
+export function PartsProgress({
+    label,
+    completed,
+    total,
+    children,
+}: {
+    label: string;
+    completed: number;
+    total: number;
+    /** What the count says, such as "4/9 done". */
+    children: ReactNode;
+}) {
+    return (
+        <div className="grid gap-1" data-parts-progress>
+            <ProgressCount label={label}>{children}</ProgressCount>
+            <div aria-hidden className="h-1.5 overflow-hidden rounded-full bg-(--soft)">
+                <div
+                    className="h-full rounded-full bg-(--st-done)"
+                    style={{ width: `${total > 0 ? (completed / total) * 100 : 0}%` }}
+                />
+            </div>
+        </div>
+    );
+}
+
+/** The activity under the steps: its track, then its label. */
+export function ProgressActivity({ children }: { children: ReactNode }) {
+    return <div className="grid gap-1">{children}</div>;
+}
+
+/** The slices under the steps: their `count` line, a slice `bar` when the steps don't hold it, and a SliceChip each. */
+export function SliceChips({ count, bar, children }: { count: ReactNode; bar?: ReactNode; children: ReactNode }) {
+    return (
+        <div className="grid min-w-0 grid-cols-[minmax(0,1fr)] gap-2" data-slices>
+            {count}
+            {bar && <div aria-hidden>{bar}</div>}
+            <ul className="m-0 flex list-none flex-wrap gap-1.5 p-0">{children}</ul>
+        </div>
+    );
+}
+
+/** A slice as a chip: where its ticket is saved, its mark, number, title (muted when done, medium while active) and
+ *  state; `title` names it in full. */
+export function SliceChip({
+    title,
+    source,
+    progress,
+    number,
+    name,
+}: {
+    title: string;
+    source: ReactNode;
+    progress: SliceProgress;
+    number?: number | undefined;
+    name: string;
+}) {
+    return (
+        <li
+            title={title}
+            className="inline-flex max-w-full items-center gap-1.5 rounded-full border border-(--border) bg-(--card) py-0.5 ps-1 pe-2.5 text-xs"
+        >
+            {source}
+            <SliceMark progress={progress} />
+            {!!number && <span className="shrink-0 text-(--muted-foreground) tabular-nums">#{number}</span>}
+            <span
+                className={`min-w-0 truncate ${progress === 'done' ? 'text-(--muted-foreground)' : progress === 'active' ? 'font-medium' : ''}`}
+            >
+                {name}
+            </span>
+            <span className="shrink-0 text-[11px] text-(--muted-foreground)">{progress}</span>
+        </li>
+    );
+}

package/src/board/List.tsx

@@ -0,0 +1,154 @@
+import type { ReactNode } from 'react';
+
+import { Button } from '../actions/Button';
+import { Badge } from '../display/Badge';
+import { Loading } from '../feedback/Loading';
+import { SidebarNavigationItem } from '../layout/sidebar/SidebarNavigationItem';
+import { buttonKind } from './ButtonKinds';
+
+interface ListButtonProps {
+    label: string;
+    icon: ReactNode;
+    /** How many items are in List; none while the first read could still add some, which shows a loading cue. */
+    count: number | undefined;
+    loadingLabel: string;
+    onOpen: () => void;
+}
+
+/** The title bar's List button, "List <count>": an App control whose label folds away, for screen readers only, on a
+ *  title bar under 70rem. */
+export function ListButton({ label, icon, count, loadingLabel, onOpen }: ListButtonProps) {
+    return (
+        <Button {...buttonKind('control')} className="list-button px-2" leftIcon={icon} title={label} onClick={onOpen}>
+            <span className="@max-[70rem]:sr-only">{label}</span>
+            {count === undefined ? <Loading presentation="inline" title={loadingLabel} /> : <Badge>{count}</Badge>}
+        </Button>
+    );
+}
+
+/** A group in the List's left pane: its icon, its name and how many of its items match; a group still reading shows
+ *  no count. */
+export function ListGroupItem({
+    label,
+    count,
+    icon,
+    active,
+    onPick,
+}: {
+    label: string;
+    count?: number;
+    icon: ReactNode;
+    active: boolean;
+    onPick: () => void;
+}) {
+    return (
+        <SidebarNavigationItem active={active} onClick={onPick}>
+            {icon}
+            <span className="name min-w-0 flex-1 truncate text-left">{label}</span>
+            {count !== undefined && <span className="count text-base-700 text-xs tabular-nums">{count}</span>}
+        </SidebarNavigationItem>
+    );
+}
+
+interface ListHeaderProps {
+    /** The search field, and beside it Add item. */
+    search: ReactNode;
+    add: ReactNode;
+    /** The chosen group's name and how many of its items show; no count while it's still reading. */
+    title: string;
+    count?: number;
+    /** After the count: a toggle that scopes the board to the group, and at the right the sort menu. */
+    scope?: ReactNode;
+    sort: ReactNode;
+    filters: ReactNode;
+}
+
+/** The List's right pane's head: the search with Add item, then the chosen group with its count, scope toggle and sort,
+ *  then the filters. */
+export function ListHeader({ search, add, title, count, scope, sort, filters }: ListHeaderProps) {
+    return (
+        <div className="flex shrink-0 flex-col gap-2 px-5 sm:px-6">
+            <div className="flex items-center gap-2 [&>[data-slot=button]]:shrink-0">
+                {search}
+                {add}
+            </div>
+            <div className="flex min-w-0 items-center gap-2">
+                <span className="text-base-content truncate text-sm font-semibold">{title}</span>
+                {count !== undefined && <Badge>{count}</Badge>}
+                {scope}
+                <span className="sort ml-auto">{sort}</span>
+            </div>
+            {filters}
+        </div>
+    );
+}
+
+interface ListItemRowProps {
+    /** The item's id, as `data-item`. */
+    item: string;
+    /** Its title in full, for the tooltip. */
+    name: string;
+    onOpen: () => void;
+    /** Where the item comes from. */
+    source: ReactNode;
+    /** The ticket's reference, such as "#61", before the title; none for an item with no ticket. */
+    reference?: string;
+    title: string;
+    /** The repository's icon, when the list mixes repositories, and the meta line's text: its name and age. */
+    repoIcon?: ReactNode;
+    meta: string;
+    /** After the meta line: the item's kind, labels and sync state. */
+    chips?: ReactNode;
+    /** More under the meta line, such as a work item's fields. */
+    details?: ReactNode;
+}
+
+/** An item in the List's right pane, opening the item dialog. */
+export function ListItemRow({
+    item,
+    name,
+    onOpen,
+    source,
+    reference,
+    title,
+    repoIcon,
+    meta,
+    chips,
+    details,
+}: ListItemRowProps) {
+    return (
+        <button
+            type="button"
+            onClick={onOpen}
+            data-item={item}
+            title={name}
+            className="hover:bg-base-200/70 focus-visible:outline-primary flex w-full min-w-0 items-start gap-2 rounded-md px-2 py-1.5 text-left focus-visible:outline-2 focus-visible:-outline-offset-2"
+        >
+            {source}
+            <span className="min-w-0 flex-1">
+                <span className="text-base-content block truncate text-[13px] leading-5 font-medium">
+                    {reference ? <span className="text-base-700 font-normal">{reference} </span> : null}
+                    {title}
+                </span>
+                <span className="flex min-w-0 flex-wrap items-center gap-x-1.5 gap-y-1">
+                    <span className="text-base-700 me-1 flex min-w-0 items-center gap-1 text-[11px] leading-4">
+                        {repoIcon}
+                        <span className="min-w-0 truncate tabular-nums">{meta}</span>
+                    </span>
+                    {chips}
+                </span>
+                {details}
+            </span>
+        </button>
+    );
+}
+
+/** What the List says in place of items: nothing matches, nothing in List, or still loading. With `reading`, it
+ *  follows items as more may arrive. */
+export function ListNote({ children, reading = false }: { children: ReactNode; reading?: boolean }) {
+    return (
+        <p className={`text-base-700 m-0 p-4 text-sm ${reading ? '' : 'empty'}`} data-reading={reading || undefined}>
+            {children}
+        </p>
+    );
+}

package/src/board/LoadingScreen.tsx

@@ -0,0 +1,78 @@
+/** The Lar mark's paths on its viewBox, drawn in the order the screen animates them. */
+export interface LoadingMark {
+    viewBox: string;
+    /** The block, which springs in first, in the brand's block colour. */
+    block: string;
+    blockColor: string;
+    /** The L's centre line, which a stroke `bar` wide traces around the block. */
+    centreLine: string;
+    bar: number;
+    /** The filled L, which stands in for the trace once it is drawn. */
+    l: string;
+}
+
+/** A line of the screen's step text; a new `id` rolls it in. */
+export interface LoadingLine {
+    id: number;
+    text: string;
+}
+
+interface LoadingScreenProps {
+    mark: LoadingMark;
+    /** The product's name after the lockup's "ar", such as "Factory". */
+    product: string;
+    /** Whether the mark is already drawn, as by the desktop's starting page; otherwise it plays its draw. */
+    drawn: boolean;
+    /** Fades the screen out, once. */
+    leaving: boolean;
+    /** The step line, and for a moment after a change the old one rolling out. */
+    line: LoadingLine;
+    leavingLine?: LoadingLine;
+    /** Whether the line rolled in; the first line and every line under reduced motion just show. */
+    rolled: boolean;
+}
+
+/**
+ * The board's loading screen: the Lar lockup, whose L draws itself around the block, over one line naming the first
+ * read's step. It covers the window, drags it, and fades out once.
+ */
+export function LoadingScreen({ mark, product, drawn, leaving, line, leavingLine, rolled }: LoadingScreenProps) {
+    return (
+        <div className={`loading-screen ${drawn ? 'is-drawn' : ''} ${leaving ? 'is-leaving' : ''}`}>
+            <div className="loading-lockup">
+                <div className="loading-wordmark">
+                    <svg className="loading-mark" viewBox={mark.viewBox} aria-hidden>
+                        <path className="loading-mark-block" d={mark.block} fill={mark.blockColor} />
+                        <path
+                            className="loading-mark-trace"
+                            d={mark.centreLine}
+                            pathLength={1}
+                            fill="none"
+                            stroke="currentColor"
+                            strokeWidth={mark.bar}
+                            strokeLinecap="butt"
+                            strokeLinejoin="miter"
+                        />
+                        <path className="loading-mark-fill" d={mark.l} fill="currentColor" />
+                    </svg>
+                    <span className="loading-lar">
+                        <span className="loading-lar-slide">ar</span>
+                    </span>
+                    <span className="loading-factory">{product}</span>
+                </div>
+                <p className="loading-line" role="status">
+                    <span className="loading-line-slot">
+                        {leavingLine && (
+                            <span key={leavingLine.id} className="loading-roll-out" aria-hidden>
+                                {leavingLine.text}
+                            </span>
+                        )}
+                        <span key={line.id} className={rolled ? 'loading-roll-in' : undefined}>
+                            {line.text}
+                        </span>
+                    </span>
+                </p>
+            </div>
+        </div>
+    );
+}

package/src/board/NeedsYou.tsx

@@ -0,0 +1,30 @@
+// Why a piece of work waits on the user, in the item dialog: the reason and the choices the board offers for it.
+
+import type { ReactNode } from 'react';
+
+import { WARNING_PANEL } from './RowStyles';
+
+/** The reason a piece of work needs you, in the warning tone, then the `actions` that answer it and any `result`. */
+export function NeedsYouNotice({
+    reason,
+    actions,
+    children,
+}: {
+    reason: ReactNode;
+    actions: ReactNode;
+    /** What the last choice left to say, under the actions. */
+    children?: ReactNode;
+}) {
+    return (
+        <div className={`grid gap-2 ${WARNING_PANEL}`} data-needs-you-reason>
+            <p className="m-0 font-medium text-(--warning-foreground)">{reason}</p>
+            <span className="flex flex-wrap gap-1.5">{actions}</span>
+            {children}
+        </div>
+    );
+}
+
+/** What a choice's cleanup left to say, announced. */
+export function NeedsYouResult({ children }: { children: ReactNode }) {
+    return <p role="alert">{children}</p>;
+}

package/src/board/Onboarding.tsx

@@ -0,0 +1,124 @@
+// Lar Factory's onboarding: the empty board's area, the cards of Projects still setting up, the setup dialog's
+// progress and steps, and the T3 projects its first step lists.
+
+import { FolderPlusIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { Badge } from '../display/Badge';
+import type { DataAttributes } from './DataAttributes';
+
+/** The board's main area while it has nothing to show, such as before its first Project: it scrolls on its own. */
+export function EmptyBoard({ children, ...data }: { children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className="min-h-0 flex-1 overflow-y-auto">
+            {children}
+        </div>
+    );
+}
+
+/** The cards of Projects still setting up, above the board: at most about a third of its height, then scrolling. */
+export function SetupCardList({ children }: { children: ReactNode }) {
+    return <div className="grid max-h-[35%] shrink-0 gap-2 overflow-y-auto">{children}</div>;
+}
+
+/** The setup dialog's place under its title: the Project's `icon` beside the `place` line, over the `progress` bar. */
+export function SetupHeader({ icon, place, progress }: { icon?: ReactNode; place: ReactNode; progress: ReactNode }) {
+    return (
+        <div className="grid shrink-0 gap-2 px-5 pb-4 sm:px-6">
+            <div className="flex min-w-0 items-center gap-2">
+                {icon}
+                {place}
+            </div>
+            {progress}
+        </div>
+    );
+}
+
+/** A setup step's parts, one under the other: close together for a list of `checks`, further apart for a `form`'s
+ *  groups. */
+export function SetupStep({
+    presentation = 'checks',
+    children,
+    ...data
+}: { presentation?: 'checks' | 'form'; children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className={`grid min-w-0 ${presentation === 'form' ? 'gap-5' : 'gap-3'}`}>
+            {children}
+        </div>
+    );
+}
+
+/**
+ * A T3 project on one line: its `icon`, its `name` and `badge`, then its `path`, which gives way first, with the
+ * `fullPath` on hover and for screen readers. A long name leaves room for some path beside the badge on a narrow page,
+ * and takes at most half the line from sm up.
+ */
+export function ProjectLine({
+    icon,
+    name,
+    badge,
+    path,
+    fullPath,
+}: {
+    icon: ReactNode;
+    name: string;
+    badge?: string | null | undefined;
+    path: string;
+    fullPath: string;
+}) {
+    return (
+        <span className="flex min-w-0 flex-1 items-center gap-2 text-sm">
+            {icon}
+            <span title={name} className="max-w-[30%] shrink-0 truncate font-medium sm:max-w-1/2">
+                {name}
+            </span>
+            {badge && (
+                <span className="shrink-0 whitespace-nowrap">
+                    <Badge>{badge}</Badge>
+                </span>
+            )}
+            <span
+                data-project-path
+                aria-hidden
+                title={fullPath}
+                className="text-base-700 min-w-0 flex-1 truncate text-xs"
+            >
+                {path}
+            </span>
+            <span className="sr-only">{fullPath}</span>
+        </span>
+    );
+}
+
+/** The choice that adds a folder as a new project: the folder icon, its `title`, then a muted `hint` that gives way. */
+export function AddFolderLine({ title, hint }: { title: string; hint: string }) {
+    return (
+        <span className="flex min-w-0 flex-1 items-center gap-2">
+            <FolderPlusIcon aria-hidden className="size-4 shrink-0" />
+            <span className="min-w-0 font-medium wrap-anywhere">{title}</span>
+            <span className="text-base-700 min-w-0 flex-1 truncate text-xs">{hint}</span>
+        </span>
+    );
+}
+
+/** What a choice asks for once picked, such as the folder to add, framed under the choices. */
+export function ChoiceDetails({ children }: { children: ReactNode }) {
+    return <div className="grid gap-3 rounded-lg border p-3">{children}</div>;
+}
+
+/** A list of projects that can't be picked, such as in a framed Disclosure. */
+export function ProjectList({ children }: { children: ReactNode }) {
+    return <ul className="m-0 grid min-w-0 list-none gap-2 p-0">{children}</ul>;
+}
+
+/** A project in a ProjectList, with the `reason` it can't be picked under it, lined up with its name. */
+export function ProjectListItem({ reason, children }: { reason?: string | undefined; children: ReactNode }) {
+    if (reason === undefined) return <li className="flex min-w-0">{children}</li>;
+
+    return (
+        <li className="grid min-w-0 gap-0.5">
+            {children}
+            <span className="text-base-700 pl-6 text-xs">{reason}</span>
+        </li>
+    );
+}