@lar-works/design-system 0.2.0 → 0.3.0

package/src/board/ItemDetails.tsx

@@ -0,0 +1,435 @@
+// What Lar Factory's item dialog shows from a piece of work's details: its sections' headings, the meta area's facts
+// and people, the main column's description, record and comments, and the sidebar's lists.
+
+import { CircleCheckIcon, CircleDotIcon } from 'lucide-react';
+import type { ReactNode, Ref } from 'react';
+
+import type { DataAttributes } from './DataAttributes';
+
+const headings = {
+    section: 'm-0 text-[13px] font-medium',
+    muted: 'm-0 text-[13px] font-medium text-(--muted-foreground)',
+    label: 'm-0 text-[11px] font-medium tracking-wider text-(--muted-foreground) uppercase',
+} as const;
+
+/** A section's heading: a sidebar `section`'s, a `muted` one over the comments or a description's own section, or the
+ *  small uppercase `label` over the description and the record. `as` a `label` it names the field `htmlFor` names, or
+ *  as a `span` a group that names itself. */
+export function DetailsHeading({
+    presentation = 'section',
+    as = 'h2',
+    htmlFor,
+    children,
+}: {
+    presentation?: keyof typeof headings;
+    as?: 'h2' | 'label' | 'span';
+    htmlFor?: string | undefined;
+    children: ReactNode;
+}) {
+    if (as === 'label')
+        return (
+            <label htmlFor={htmlFor} className={headings[presentation]}>
+                {children}
+            </label>
+        );
+
+    if (as === 'span') return <span className={headings[presentation]}>{children}</span>;
+
+    return <h2 className={headings[presentation]}>{children}</h2>;
+}
+
+/** A sidebar section, or a section of the body such as a concept's parts: its heading over its content. */
+export function DetailsSection({
+    heading,
+    children,
+    ...data
+}: {
+    heading: ReactNode;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <section {...data} className="grid min-w-0 grid-cols-[minmax(0,1fr)] gap-2">
+            <DetailsHeading>{heading}</DetailsHeading>
+            {children}
+        </section>
+    );
+}
+
+/** A section of the description, such as Acceptance Criteria: its muted heading over its text. */
+export function TextSection({ heading, children }: { heading: ReactNode; children: ReactNode }) {
+    return (
+        <section className="grid min-w-0 gap-2">
+            <DetailsHeading presentation="muted">{heading}</DetailsHeading>
+            {children}
+        </section>
+    );
+}
+
+/**
+ * A section of the main column, beside the sidebar: the record, description or comments, its `header` over its
+ * content. When it `fill`s, its content takes the height left.
+ */
+export function MainSection({
+    as: Tag = 'div',
+    header,
+    fill = false,
+    children,
+    ...data
+}: {
+    as?: 'div' | 'section';
+    header: ReactNode;
+    fill?: boolean;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <Tag
+            {...data}
+            className={`grid min-w-0 gap-2 ${fill ? 'min-h-0 grid-rows-[auto_minmax(0,1fr)]' : ''} @min-[45rem]:col-start-1`}
+        >
+            {header}
+            {children}
+        </Tag>
+    );
+}
+
+/** A main section's header row: its small uppercase `heading`, then its actions at the end. */
+export function SectionHeader({ heading, children }: { heading: ReactNode; children?: ReactNode }) {
+    return (
+        <div className="flex h-7 items-center justify-between gap-2">
+            <DetailsHeading presentation="label">{heading}</DetailsHeading>
+            {children && <span className="flex min-w-0 items-center gap-3">{children}</span>}
+        </div>
+    );
+}
+
+/** A short status in a section's header, such as a save that could not be read back, truncating. */
+export function HeaderStatus({ children }: { children: string }) {
+    return (
+        <span className="truncate text-xs text-(--muted-foreground)" role="status" title={children}>
+            {children}
+        </span>
+    );
+}
+
+/** A line of the details in the body size: an error, announced, or a muted empty state. `mainColumn` keeps it in the
+ *  main column beside the sidebar. */
+export function DetailsText({
+    tone = 'muted',
+    mainColumn = false,
+    children,
+}: {
+    tone?: 'muted' | 'error';
+    mainColumn?: boolean;
+    children: ReactNode;
+}) {
+    return (
+        <p
+            className={`m-0 text-sm ${tone === 'error' ? 'text-(--error-foreground)' : 'text-(--muted-foreground)'}${mainColumn ? ' @min-[45rem]:col-start-1' : ''}`}
+            role={tone === 'error' ? 'alert' : undefined}
+        >
+            {children}
+        </p>
+    );
+}
+
+/** A placeholder that keeps the main column's place while the details load. */
+export function MainColumnSlot({ children }: { children: ReactNode }) {
+    return <div className="@min-[45rem]:col-start-1">{children}</div>;
+}
+
+/** The meta area under the summary: its facts, wrapping onto as many lines as the width needs. */
+export function MetaArea({ children, ...data }: { children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className="flex min-w-0 flex-wrap items-center gap-x-5 gap-y-2">
+            {children}
+        </div>
+    );
+}
+
+/**
+ * A labelled fact: in the meta area, its value wrapping rather than running past the dialog; in a `record`, a fact of
+ * the work record whose value wraps onto lines of its own.
+ */
+export function DetailFact({
+    label,
+    presentation = 'meta',
+    children,
+    ...data
+}: {
+    label: string;
+    presentation?: 'meta' | 'record';
+    children: ReactNode;
+} & DataAttributes) {
+    if (presentation === 'record')
+        return (
+            <div {...data} className="flex min-w-0 flex-wrap items-baseline gap-x-1.5 text-sm">
+                <span className="shrink-0 text-xs text-(--muted-foreground)">{label}</span>
+                {children}
+            </div>
+        );
+
+    return (
+        <div {...data} className="flex max-w-full min-w-0 items-baseline gap-1.5 text-sm">
+            <span className="shrink-0 text-xs text-(--muted-foreground)">{label}</span>
+            <span className="min-w-0 wrap-anywhere">{children}</span>
+        </div>
+    );
+}
+
+/** A line of short items, such as a review round's verdicts, wrapping. */
+export function InlineList({ items }: { items: readonly string[] }) {
+    return (
+        <ul className="m-0 flex list-none flex-wrap gap-x-3 p-0">
+            {items.map((item, index) => (
+                <li key={index}>{item}</li>
+            ))}
+        </ul>
+    );
+}
+
+/** Facts one under the other, such as a record's review rounds. */
+export function FactList({ children, ...data }: { children: ReactNode } & DataAttributes) {
+    return (
+        <div {...data} className="grid gap-1">
+            {children}
+        </div>
+    );
+}
+
+/** The editor's slot in a main section: a column that takes the height left when it `fill`s. */
+export function EditorSlot({ fill, children }: { fill: boolean; children: ReactNode }) {
+    return <div className={fill ? 'flex min-h-0 flex-col' : 'contents'}>{children}</div>;
+}
+
+/** Under an editor: whether it changed, or `error` in its place, announced and wrapping, then its buttons. */
+export function EditActions({
+    status,
+    error,
+    children,
+    ...data
+}: {
+    status: string;
+    error?: string | null | undefined;
+    children: ReactNode;
+} & DataAttributes) {
+    return (
+        <div {...data} className="flex items-start gap-2">
+            {error ? (
+                <p className="m-0 me-auto min-w-0 flex-1 py-1.5 text-xs text-(--error-foreground)" role="alert">
+                    {error}
+                </p>
+            ) : (
+                <span className="me-auto min-w-0 flex-1 py-1.5 text-xs text-(--muted-foreground)">{status}</span>
+            )}
+            {children}
+        </div>
+    );
+}
+
+/** How a Spec's sync stands: its `status`, announced, then what answers it, then an `error`, announced. */
+export function SpecSync({
+    status,
+    error,
+    children,
+}: {
+    status?: string | undefined;
+    error?: string | null | undefined;
+    children?: ReactNode;
+}) {
+    return (
+        <div className="grid gap-2 text-sm" data-spec-sync>
+            {status && (
+                <p className="m-0" role="status">
+                    {status}
+                </p>
+            )}
+            {children}
+            {error && (
+                <p className="m-0 text-(--error-foreground)" role="alert">
+                    {error}
+                </p>
+            )}
+        </div>
+    );
+}
+
+/** Linked work items, such as sub-tickets or blockers, one TicketLink each; or attachments, one AttachmentLink each. */
+export function TicketLinkList({ children }: { children: ReactNode }) {
+    return <ul className="m-0 grid list-none gap-1.5 p-0">{children}</ul>;
+}
+
+/** A linked work item: done or open (`stateLabel` names it), its `reference` and `title` linked, and its tracker's
+ *  `fields` under them. */
+export function TicketLink({
+    closed,
+    stateLabel,
+    href,
+    reference,
+    title,
+    fields,
+}: {
+    closed: boolean;
+    stateLabel: string;
+    href: string;
+    reference: string;
+    title: string;
+    fields?: ReactNode;
+}) {
+    return (
+        <li className="flex items-start gap-2 text-sm">
+            {closed ? (
+                <CircleCheckIcon aria-label={stateLabel} className="mt-0.5 size-3.5 shrink-0 text-(--success)" />
+            ) : (
+                <CircleDotIcon aria-label={stateLabel} className="mt-0.5 size-3.5 shrink-0 text-(--muted-foreground)" />
+            )}
+            <span className="min-w-0">
+                <a href={href} target="_blank" rel="noopener" className="wrap-anywhere hover:underline">
+                    <span className="text-(--muted-foreground)">{reference}</span> {title}
+                </a>
+                {fields}
+            </span>
+        </li>
+    );
+}
+
+/** An attachment's name, linked. */
+export function AttachmentLink({ href, name }: { href: string; name: string }) {
+    return (
+        <li className="text-sm">
+            <a href={href} target="_blank" rel="noopener" className="wrap-anywhere underline">
+                {name}
+            </a>
+        </li>
+    );
+}
+
+/** A sprint's count over its children: `count` ("This sprint: 2 of 5 done") and the sprint's `name`. */
+export function SprintCount({ count, name }: { count: string; name: string }) {
+    return (
+        <div className="text-sm">
+            <p className="m-0 font-medium">{count}</p>
+            <p className="m-0 text-xs text-(--muted-foreground)">{name}</p>
+        </div>
+    );
+}
+
+/** The work an item waits on, struck through once closed. */
+export function WaitsOnList({ items }: { items: readonly { key: string; title: string; closed: boolean }[] }) {
+    return (
+        <ul className="m-0 grid list-none gap-1.5 p-0 text-sm" data-waits-on>
+            {items.map((item) => (
+                <li key={item.key} className={item.closed ? 'text-(--muted-foreground) line-through' : ''}>
+                    {item.title}
+                </li>
+            ))}
+        </ul>
+    );
+}
+
+/** Chips in a wrapping line, grouped with no box of their own, such as the labels fact's, for tests to name. */
+export function ChipGroup({ children, ...data }: { children: ReactNode } & DataAttributes) {
+    return (
+        <span {...data} className="contents">
+            {children}
+        </span>
+    );
+}
+
+/** A popover's panel for picking labels: 18rem wide, its picker over its status. */
+export function LabelEditorPanel({ children }: { children: ReactNode }) {
+    return <div className="grid w-72 gap-2">{children}</div>;
+}
+
+/** A kind change that failed: each of its `lines`, then the `action` that retries it, announced. */
+export function ChangeFailed({
+    lines,
+    action,
+    ...data
+}: {
+    lines: readonly string[];
+    action: ReactNode;
+} & DataAttributes) {
+    return (
+        <div {...data} role="alert" className="grid w-full justify-items-start gap-1 text-xs text-(--error-foreground)">
+            {lines.map((line, index) => (
+                <p key={index} className="m-0">
+                    {line}
+                </p>
+            ))}
+            {action}
+        </div>
+    );
+}
+
+/** Where the item's kind and its ticket's disagree: the `message`, the `actions` that answer it, then a `hint` and any
+ *  `error`, which the caller renders as caption Text. */
+export function KindQuestion({
+    message,
+    actions,
+    children,
+    ...data
+}: {
+    message: string;
+    actions: ReactNode;
+    children?: ReactNode;
+} & DataAttributes) {
+    return (
+        <div {...data} className="grid w-full gap-2 rounded-lg border border-(--border) p-3">
+            <p className="m-0 text-sm">{message}</p>
+            <span className="flex flex-wrap gap-2">{actions}</span>
+            {children}
+        </div>
+    );
+}
+
+/** A ticket's outgoing title and text, as the tracker will receive them; the labels name each for assistive
+ *  technology. */
+export function OutgoingTicket({
+    title,
+    text,
+    titleLabel,
+    textLabel,
+}: {
+    title: string;
+    text: string;
+    titleLabel: string;
+    textLabel: string;
+}) {
+    return (
+        <>
+            <div aria-label={titleLabel} className="font-medium wrap-anywhere">
+                {title}
+            </div>
+            <pre
+                aria-label={textLabel}
+                className="m-0 max-h-64 overflow-auto text-xs wrap-anywhere whitespace-pre-wrap"
+            >
+                {text}
+            </pre>
+        </>
+    );
+}
+
+/** A check's run: its `command`, then what it says of the run. */
+export function CheckRun({ command, children }: { command: string; children: ReactNode }) {
+    return (
+        <section className="min-w-0 rounded border border-(--border) p-2">
+            <code className="wrap-anywhere whitespace-pre-wrap">{command}</code>
+            {children}
+        </section>
+    );
+}
+
+/** A section's own scrolling panel that focus moves to when it opens, such as Create issue's; `label` names it. */
+export function FocusPanel({ label, ref, children }: { label: string; ref?: Ref<HTMLElement>; children: ReactNode }) {
+    return (
+        <section
+            ref={ref}
+            tabIndex={-1}
+            aria-label={label}
+            className="grid max-h-[50dvh] w-full gap-3 overflow-y-auto pt-1"
+        >
+            {children}
+        </section>
+    );
+}

package/src/board/ItemDialog.tsx

@@ -0,0 +1,179 @@
+// The frame of Lar Factory's item dialog: the summary under its title, the body's column with the main column and the
+// sidebar beside it, its notes, and the footer's groups of actions.
+
+import type { ReactNode } from 'react';
+
+import type { DataAttributes } from './DataAttributes';
+import { WARNING_PANEL } from './RowStyles';
+
+/**
+ * The summary under the dialog's title, a row each: `line` (the item's source, repository, status and age), its
+ * `parent`, its `kind` and its ticket `actions`.
+ */
+export function ItemSummary({
+    line,
+    parent,
+    kind,
+    actions,
+    ...data
+}: {
+    line: ReactNode;
+    parent?: ReactNode;
+    kind: ReactNode;
+    actions: ReactNode;
+} & DataAttributes) {
+    return (
+        <div
+            {...data}
+            className="border-base-300 text-base-700 @container grid shrink-0 gap-1 border-b px-5 pb-3 text-xs sm:px-6"
+        >
+            <div className="flex min-w-0 flex-wrap items-center gap-2">{line}</div>
+            {parent}
+            <div className="flex flex-wrap items-center gap-2">{kind}</div>
+            <div className="flex flex-wrap items-start gap-2">{actions}</div>
+        </div>
+    );
+}
+
+/** The summary's status word, in the text colour. */
+export function SummaryStatus({ children }: { children: ReactNode }) {
+    return <span className="text-base-content font-medium">{children}</span>;
+}
+
+/** The summary's age, which a narrow dialog leaves out. */
+export function SummaryAge({ children }: { children: ReactNode }) {
+    return <span className="min-w-0 truncate @max-[30rem]:hidden">{children}</span>;
+}
+
+/** What blocks the item, as a small chip in the danger colours. */
+export function SummaryBlocked({ children }: { children: ReactNode }) {
+    return <span className="rounded bg-(--error-surface) px-1.5 text-(--error-foreground)">{children}</span>;
+}
+
+/** The item's parent: `prefix` ("Part of"), then its `name`, linked when `href` opens it. */
+export function SummaryParent({
+    prefix,
+    name,
+    href,
+    ...data
+}: {
+    prefix: string;
+    name: string;
+    href?: string | undefined;
+} & DataAttributes) {
+    return (
+        <p {...data} className="m-0 min-w-0 wrap-anywhere">
+            {prefix}{' '}
+            {href ? (
+                <a href={href} target="_blank" rel="noopener" className="underline">
+                    {name}
+                </a>
+            ) : (
+                name
+            )}
+        </p>
+    );
+}
+
+/** A labelled control the summary opens in place, such as Attach a ticket's picker: `label` over it. */
+export function SummaryPanel({ label, children }: { label: string; children: ReactNode }) {
+    return (
+        <section aria-label={label} className="grid gap-1.5 pt-1">
+            <span className="text-base-content text-xs font-medium">{label}</span>
+            {children}
+        </section>
+    );
+}
+
+/**
+ * The dialog body's column: the progress, notes, meta area, record, description, comments and sidebar, one under the
+ * other; when it `fill`s, a column whose description and comments take what the rest leave.
+ */
+export function ItemDialogBody({ fill, children, ...data }: { fill: boolean; children: ReactNode } & DataAttributes) {
+    return (
+        <div
+            {...data}
+            className={`@container gap-3 pt-2 ${fill ? 'flex min-h-0 flex-1 flex-col' : 'grid grid-cols-[minmax(0,1fr)]'}`}
+        >
+            {children}
+        </div>
+    );
+}
+
+/**
+ * The main column with the sidebar beside it once the dialog is 45rem wide, when there is an `aside`. Filling, the
+ * main column's open editor takes the height the rest leaves.
+ */
+export function ItemDialogColumns({ aside, fill, children }: { aside: boolean; fill: boolean; children: ReactNode }) {
+    const rows = fill
+        ? 'min-h-0 flex-1 grid-rows-[minmax(0,1fr)_auto]'
+        : aside
+          ? '@min-[45rem]:grid-rows-[auto_1fr]'
+          : '';
+
+    return (
+        <div
+            className={`grid grid-cols-[minmax(0,1fr)] gap-x-6 gap-y-4 ${aside ? '@min-[45rem]:grid-cols-[minmax(0,1fr)_16rem]' : ''} ${rows}`}
+        >
+            {children}
+        </div>
+    );
+}
+
+/** The sidebar beside the main column, ruled off from it once there is room. */
+export function ItemDialogAside({ children }: { children: ReactNode }) {
+    return (
+        <aside className="grid min-w-0 grid-cols-[minmax(0,1fr)] content-start gap-4 @min-[45rem]:col-start-2 @min-[45rem]:row-span-2 @min-[45rem]:row-start-1 @min-[45rem]:border-l @min-[45rem]:border-(--border) @min-[45rem]:pl-6">
+            {children}
+        </aside>
+    );
+}
+
+/** A warning about the item, such as why it is paused, in the warning panel: `icon` (a status glyph) before it when
+ *  given. */
+export function WarningNote({ icon, children, ...data }: { icon?: ReactNode; children: ReactNode } & DataAttributes) {
+    if (icon)
+        return (
+            <div {...data} className={`flex items-center gap-3 ${WARNING_PANEL}`}>
+                {icon}
+                <span className="min-w-0 flex-1 font-medium text-(--warning-foreground)">{children}</span>
+            </div>
+        );
+
+    return (
+        <p {...data} className={`m-0 ${WARNING_PANEL} font-medium text-(--warning-foreground)`}>
+            {children}
+        </p>
+    );
+}
+
+/** Why the factory can't write to the item's tracker, announced, and the `action` that checks again. */
+export function AccessNotice({ message, action }: { message: string; action: ReactNode }) {
+    return (
+        <div role="status">
+            <p>{message}</p>
+            {action}
+        </div>
+    );
+}
+
+/** A group of the footer's actions: the `leading` ones that move the item, in small text, or the rest at its end. */
+export function DialogActions({
+    presentation = 'trailing',
+    children,
+}: {
+    presentation?: 'leading' | 'trailing';
+    children: ReactNode;
+}) {
+    return (
+        <span
+            className={
+                presentation === 'leading'
+                    ? 'inline-flex items-center gap-3 text-xs'
+                    : 'inline-flex items-center gap-1.5'
+            }
+        >
+            {children}
+        </span>
+    );
+}