@sole-ui/react 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @sole-ui/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sole's design system for React and Tailwind CSS v4: the design tokens (colour, label hues, type scale, radius, elevation, motion) and the shared and Sole HQ components, typed, tested and copied from Sole HQ with the same look and behaviour.
+
+Light mode and desktop only. React 18.3 and 19.
+
+Every part, live, with its variants: https://mindninjax.github.io/sole-design-system/components/
+Every token: https://mindninjax.github.io/sole-design-system/
+
+## Install
+
+```sh
+npm install @sole-ui/react
+```
+
+## Components
+
+Peer dependencies: `react`, `react-dom` (18.3 or 19), `radix-ui` and, for the styles, `tailwindcss` v4.
+
+```sh
+npm install @sole-ui/react radix-ui
+```
+
+Wrap the app in `SoleProvider` once. It gives the parts your router's link, the work clock and the tooltip provider:
+
+```tsx
+import { Link } from 'react-router';
+import { Button, SoleProvider, Toaster } from '@sole-ui/react';
+import { StatePill } from '@sole-ui/react/hq';
+
+<SoleProvider
+  linkComponent={({ href, ...props }) => <Link to={href} {...props} />}
+  timeZone="Australia/Sydney"
+  personHref={(person) => `/people/${person.id}`}
+>
+  <Button>Save</Button>
+  <StatePill state={{ name: 'In progress', group: 'started' }} />
+  <Toaster />
+</SoleProvider>
+```
+
+- `@sole-ui/react` holds the shared shadcn parts (`Button`, `Dialog`, `Select`, `Tabs`, ...), the Sole parts (`Avatar`, `PersonChip`, `Pill`, `Table`, `FilterChip`, ...) and the app shell pieces (`AppFrame`, `Sidebar`, `TopBar`, `CommandPalette`).
+- `@sole-ui/react/hq` holds the parts only Sole HQ uses (`StateIcon`, `DueChip`, `WorkItemRow`, `BoardCard`, ...).
+- The parts are presentational: no router, no fetching. People are `SolePerson` (`id`, `name`, `avatarUrl?`, `isBot?`); links go through `SoleLink`. Pass `now` to `SoleProvider` to pin the clock in demos and tests.
+- Each part that draws an element forwards its ref, and every module starts with `'use client'`, so they work in Next.js too.
+
+## With Tailwind CSS v4
+
+Tailwind v4 is an optional peer dependency (`^4.1.0`). In your main stylesheet:
+
+```css
+@import "tailwindcss";
+@import "@sole-ui/react/styles.css";
+```
+
+That gives you:
+
+- the Sole colours as utilities (`bg-primary`, `text-muted-foreground`, `border-border`), the label hues (`.hue-blue` with `bg-tag-bg`, `text-tag-fg`) and the radius, shadow and type scales (`text-body`, `text-strong`, `text-micro`);
+- Inter Variable as the sans font, through `@fontsource-variable/inter`, which installs with the package;
+- the base layer: page background and text colour, tabular numbers on `time` and `kbd`, and no motion for people who asked their system for less.
+
+## Without Tailwind
+
+`tokens.css` is plain CSS custom properties on `:root`, plus the `.hue-*` classes. It works in any project:
+
+```css
+@import "@sole-ui/react/tokens.css";
+
+.card {
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--elevation-sm);
+}
+```
+
+(The `@theme` and `@utility` blocks in the file are for Tailwind. Other tools ignore them.)
+
+## In JavaScript
+
+```js
+import { tokens } from "@sole-ui/react";
+
+tokens.color.primary.$value; // "#0270d6"
+```
+
+`tokens` is the token tree as a plain object, typed so that `tokens.color.primary` is checked by the compiler.
+
+## tokens.json
+
+`@sole-ui/react/tokens.json` is the same tree in the [DTCG](https://www.designtokens.org/) format (`$value`, `$type`, `$description`), for design tools and other generators:
+
+```js
+import tokens from "@sole-ui/react/tokens.json" with { type: "json" };
+```
+
+## Source
+
+https://github.com/mindninjaX/sole-design-system. The values never change here first: if the look changes, it changes in Sole HQ, and the tokens follow.

package/dist/components/shell/app-frame.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+export interface AppFrameProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'children'> {
+    /** A `Sidebar`. */
+    sidebar: React.ReactNode;
+    /** A panel docked beside the content, such as an assistant. Leave it out when closed. */
+    aside?: React.ReactNode;
+    /** A strip above the content panel. It sits in the 8px gap, so the panel gets no top gap of its own. */
+    banner?: React.ReactNode;
+    /** Classes for the content panel, for an app that restyles the screen beside its aside. */
+    contentClassName?: string;
+    /** The screen: usually a `Page`. */
+    children: React.ReactNode;
+}
+export declare const AppFrame: React.ForwardRefExoticComponent<AppFrameProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/shell/app-frame.js

@@ -0,0 +1,8 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { cn } from '../../lib/cn.js';
+export const AppFrame = React.forwardRef(function AppFrame({ sidebar, aside, banner, contentClassName, children, className, ...props }, ref) {
+    return (_jsxs("div", { ref: ref, "data-app-shell": true, className: cn('flex h-dvh w-full min-w-[1024px] overflow-hidden bg-background', className), ...props, children: [sidebar, _jsxs("div", { className: "flex min-w-0 flex-1 flex-col", children: [banner, _jsxs("div", { className: cn('flex min-h-0 flex-1 gap-2 pr-2 pb-2', !banner && 'pt-2'), children: [_jsx("main", { id: "content", "data-pane": "content", "data-has-aside": aside ? true : undefined, className: cn('relative min-w-0 flex-1 overflow-hidden rounded-xl border border-border bg-card', contentClassName), children: children }), aside] })] })] }));
+});
+AppFrame.displayName = 'AppFrame';

package/dist/components/shell/command-palette.d.ts

@@ -0,0 +1,32 @@
+import * as React from 'react';
+export interface CommandPaletteItem {
+    id: string;
+    label: string;
+    /** An icon element, drawn at 14px. */
+    icon?: React.ReactNode;
+    /** The key hint on the right, as words: "C" or "Cmd J". */
+    shortcut?: string;
+    /** Runs after the palette has closed. */
+    onSelect: () => void;
+}
+export interface CommandPaletteGroup {
+    heading: string;
+    items: CommandPaletteItem[];
+}
+export interface CommandPaletteProps {
+    groups: CommandPaletteGroup[];
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    placeholder?: string;
+    /** Shown when nothing matches what was typed. */
+    empty?: string;
+    /** The palette's name for screen readers, and the search field's label. */
+    title?: string;
+    description?: string;
+    /** false when the caller filters the rows itself. */
+    filter?: boolean;
+    /** The typed words, when the caller controls them. */
+    query?: string;
+    onQueryChange?: (query: string) => void;
+}
+export declare function CommandPalette({ groups, open, onOpenChange, placeholder, empty, title, description, filter, query, onQueryChange, }: CommandPaletteProps): React.JSX.Element;

package/dist/components/shell/command-palette.js

@@ -0,0 +1,30 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { Kbd } from '../sole/kbd.js';
+import { CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandShortcut } from '../ui/command.js';
+/** 20.2's group headings: 26px from a heading to its first row, 31px from a last row to the next heading. */
+const GROUP_CLASS = '[&_[cmdk-group-heading]]:pt-[7px] [&_[cmdk-group-heading]]:pb-0.5';
+const matches = (text, term) => text.toLowerCase().includes(term.toLowerCase());
+export function CommandPalette({ groups, open, onOpenChange, placeholder = 'Search or jump to', empty = 'Nothing matches that.', title = 'Command palette', description = 'Search, or jump to a screen', filter = true, query, onQueryChange, }) {
+    const [ownQuery, setOwnQuery] = React.useState('');
+    const text = query ?? ownQuery;
+    const setText = (value) => {
+        if (query === undefined)
+            setOwnQuery(value);
+        onQueryChange?.(value);
+    };
+    const term = text.trim();
+    const shown = groups
+        .map((group) => ({ ...group, items: filter && term ? group.items.filter((item) => matches(item.label, term)) : group.items }))
+        .filter((group) => group.items.length > 0);
+    return (_jsxs(CommandDialog, { open: open, onOpenChange: (next) => {
+            onOpenChange(next);
+            if (!next)
+                setOwnQuery('');
+        }, title: title, description: description, shouldFilter: false, children: [_jsx(CommandInput, { value: text, onValueChange: setText, placeholder: placeholder, "aria-label": title, trailing: _jsx(Kbd, { keys: ['Esc'] }) }), _jsxs(CommandList, { children: [_jsx(CommandEmpty, { children: empty }), shown.map((group) => (_jsx(CommandGroup, { heading: group.heading, className: GROUP_CLASS, children: group.items.map((item) => (_jsxs(CommandItem, { value: item.id, onSelect: () => {
+                                onOpenChange(false);
+                                setOwnQuery('');
+                                item.onSelect();
+                            }, children: [item.icon, _jsx("span", { className: "min-w-0 flex-1 truncate", children: item.label }), item.shortcut && _jsx(CommandShortcut, { children: item.shortcut })] }, item.id))) }, group.heading)))] })] }));
+}

package/dist/components/shell/index.d.ts

@@ -0,0 +1,4 @@
+export * from './app-frame.tsx';
+export * from './command-palette.tsx';
+export * from './page.tsx';
+export * from './sidebar.tsx';

package/dist/components/shell/index.js

@@ -0,0 +1,4 @@
+export * from './app-frame.js';
+export * from './command-palette.js';
+export * from './page.js';
+export * from './sidebar.js';

package/dist/components/shell/page.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export interface Crumb {
+    label: string;
+    /** An address in the app. The last crumb is the current page, so it never links. */
+    href?: string;
+    /** A board emoji or an icon before the label. */
+    icon?: React.ReactNode;
+}
+export interface BreadcrumbsProps extends Omit<React.ComponentPropsWithoutRef<'nav'>, 'children'> {
+    crumbs: Crumb[];
+}
+export declare const Breadcrumbs: React.ForwardRefExoticComponent<BreadcrumbsProps & React.RefAttributes<HTMLElement>>;
+export interface TopBarProps extends Omit<React.ComponentPropsWithoutRef<'header'>, 'children'> {
+    crumbs: Crumb[];
+    /** Buttons for the screen, on the right. */
+    actions?: React.ReactNode;
+}
+export declare const TopBar: React.ForwardRefExoticComponent<TopBarProps & React.RefAttributes<HTMLElement>>;
+export interface PageProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'className' | 'title'> {
+    crumbs: Crumb[];
+    actions?: React.ReactNode;
+    /** Classes for the scrolling body under the top bar, not for the root. */
+    className?: string;
+}
+export declare const Page: React.ForwardRefExoticComponent<PageProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/shell/page.js

@@ -0,0 +1,22 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { ChevronRight } from 'lucide-react';
+import { cn } from '../../lib/cn.js';
+import { SoleLink } from '../../lib/sole-provider.js';
+export const Breadcrumbs = React.forwardRef(function Breadcrumbs({ crumbs, className, ...props }, ref) {
+    return (_jsx("nav", { ref: ref, "aria-label": "Breadcrumb", className: cn('min-w-0', className), ...props, children: _jsx("ol", { className: "flex min-w-0 items-center gap-1.5 text-body font-medium", children: crumbs.map((crumb, i) => {
+                const last = i === crumbs.length - 1;
+                const inner = (_jsxs(_Fragment, { children: [crumb.icon, _jsx("span", { className: "truncate", children: crumb.label })] }));
+                return (_jsxs(React.Fragment, { children: [i > 0 && _jsx(ChevronRight, { size: 14, "aria-hidden": "true", className: "shrink-0 text-faint" }), _jsx("li", { className: cn('flex min-w-0 items-center gap-1.5', last ? 'text-foreground' : 'text-muted-foreground'), "aria-current": last ? 'page' : undefined, children: crumb.href && !last ? (_jsx(SoleLink, { href: crumb.href, className: "flex min-w-0 items-center gap-1.5 rounded-sm outline-none hover:text-foreground focus-visible:shadow-[var(--focus-ring)]", children: inner })) : (inner) })] }, crumb.href ?? crumb.label));
+            }) }) }));
+});
+Breadcrumbs.displayName = 'Breadcrumbs';
+export const TopBar = React.forwardRef(function TopBar({ crumbs, actions, className, ...props }, ref) {
+    return (_jsxs("header", { ref: ref, "data-topbar": true, className: cn('flex h-12 shrink-0 items-center gap-3 border-b border-border px-4', className), ...props, children: [_jsx(Breadcrumbs, { crumbs: crumbs }), actions && _jsx("div", { className: "ml-auto flex shrink-0 items-center gap-2", children: actions })] }));
+});
+TopBar.displayName = 'TopBar';
+export const Page = React.forwardRef(function Page({ crumbs, actions, children, className, ...props }, ref) {
+    return (_jsxs("div", { ref: ref, className: "flex h-full min-h-0 flex-col", ...props, children: [_jsx(TopBar, { crumbs: crumbs, actions: actions }), _jsx("div", { "data-page-body": true, className: cn('min-h-0 flex-1 overflow-y-auto overflow-x-hidden', className), children: children })] }));
+});
+Page.displayName = 'Page';

package/dist/components/shell/sidebar.d.ts

@@ -0,0 +1,81 @@
+import * as React from 'react';
+import { type SolePerson } from '../../lib/person.ts';
+export interface SidebarProps extends React.ComponentPropsWithoutRef<'nav'> {
+    /** The 52px rail of icons instead of the 240px sidebar. Every part inside follows it. */
+    rail?: boolean;
+}
+export declare const Sidebar: React.ForwardRefExoticComponent<SidebarProps & React.RefAttributes<HTMLElement>>;
+export interface SidebarHeaderProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'children'> {
+    rail?: boolean;
+    /** Where the logo goes. */
+    href?: string;
+    /** The logo link's accessible name. */
+    label?: string;
+    /** The logo beside the collapse button. Defaults to the Sole lockup. */
+    logo?: React.ReactNode;
+    /** The logo in the rail, where it doubles as the expand button. Defaults to the Sole mark. */
+    mark?: React.ReactNode;
+    /** Collapses the sidebar, or expands the rail. Without it there is no button. */
+    onToggle?: () => void;
+}
+export declare const SidebarHeader: React.ForwardRefExoticComponent<SidebarHeaderProps & React.RefAttributes<HTMLDivElement>>;
+/** A stack of rows: 2px apart, or 4px apart and centred in the rail. */
+export declare const SidebarSection: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    rail?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+/** The middle of the sidebar: it takes the spare height and scrolls when the rows do not fit. */
+export declare const SidebarContent: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    rail?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+/** The bottom of the sidebar (settings, the user row), pinned under the scrolling middle. */
+export declare const SidebarFooter: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    rail?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+export interface SidebarItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+    /** An address in the app: the row is a link. Without it the row is a button. */
+    href?: string;
+    /** Drawn at 16px; its stroke is 1.8, and 2.1 when active. An emoji works too. */
+    icon: React.ReactNode;
+    label: string;
+    /** The current page. Sets `aria-current`. The caller decides, so a row is never current by accident. */
+    active?: boolean;
+    /** A count: `text` is drawn, `label` is what a screen reader hears ("2 unread mentions"). */
+    badge?: {
+        text: string;
+        label: string;
+    };
+    /** Keys shown on hover, as `Kbd` takes them: `['mod', 'J']`. Hidden while there is a badge. */
+    shortcut?: string[];
+    /** What the rail's tooltip adds after the label. Defaults to the shortcut's keys, else the badge's label. */
+    hint?: string;
+    /** Something at the right edge, such as a count that shows on hover (`group-hover/nav:opacity-100`). */
+    trailing?: React.ReactNode;
+    rail?: boolean;
+}
+export declare const SidebarItem: React.ForwardRefExoticComponent<SidebarItemProps & React.RefAttributes<HTMLElement>>;
+export interface SidebarGroupProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'children'> {
+    label: string;
+    /** Controlled. Leave it out and the group keeps its own state. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    rail?: boolean;
+    children: React.ReactNode;
+}
+/** A labelled, collapsible list of rows. In the rail the label becomes a short rule and the rows always show. */
+export declare const SidebarGroup: React.ForwardRefExoticComponent<SidebarGroupProps & React.RefAttributes<HTMLDivElement>>;
+export interface SidebarUserProps extends Omit<React.ComponentPropsWithoutRef<'button'>, 'children'> {
+    person: SolePerson;
+    /** The line under the name, such as "Admin". */
+    meta?: string;
+    rail?: boolean;
+    /** The menu's rows: `DropdownMenuItem`, `DropdownMenuSeparator` and the rest of `ui/dropdown-menu`. The name heads the menu. */
+    children?: React.ReactNode;
+}
+/** The user row and its menu (20.4-user-menu.png). */
+export declare const SidebarUser: React.ForwardRefExoticComponent<SidebarUserProps & React.RefAttributes<HTMLButtonElement>>;
+export interface SidebarSearchProps extends Omit<React.ComponentPropsWithoutRef<'button'>, 'children'> {
+    rail?: boolean;
+}
+/** The Search field that opens the command palette. It is a button: the palette has the real input. */
+export declare const SidebarSearch: React.ForwardRefExoticComponent<SidebarSearchProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/shell/sidebar.js

@@ -0,0 +1,113 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { ChevronDown, ChevronsUpDown, PanelLeft, Search } from 'lucide-react';
+import { cn } from '../../lib/cn.js';
+import { personName } from '../../lib/person.js';
+import { SoleLink } from '../../lib/sole-provider.js';
+import { Avatar } from '../sole/avatar.js';
+import { CountBadge } from '../sole/count-badge.js';
+import { Kbd, keysText } from '../sole/kbd.js';
+import { SoleLockup, SoleMark } from '../sole/logo.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuTrigger } from '../ui/dropdown-menu.js';
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip.js';
+// The sidebar (brand-and-ux 4.3, D2; hq/design/screens 30.1, 20.1 and 20.4): a header, the
+// destinations, collapsible groups, then the user row. 240px wide, or a 52px rail of icons
+// whose tooltips carry the label and the hint ("Inbox · 1 mention, 3 unread"). Everything
+// arrives as props or children: the app owns its nav list, its data and its router.
+/** `Sidebar` says whether it is a rail, so its parts do not each need `rail`. A part's own `rail` wins. */
+const RailContext = React.createContext(false);
+function useRail(own) {
+    const fromSidebar = React.useContext(RailContext);
+    return own ?? fromSidebar;
+}
+const itemClass = (active) => cn('flex h-8 w-full min-w-0 items-center gap-2 rounded-md px-2 text-body font-medium outline-none transition-colors duration-[120ms]', 'focus-visible:shadow-[var(--focus-ring)]', active ? 'bg-sidebar-accent text-sidebar-accent-foreground' : 'text-sidebar-foreground hover:bg-sidebar-hover hover:text-foreground');
+/** A rail button: 36 by 32, centred in the 52px rail. */
+const railClass = 'h-8 w-9 justify-center px-0';
+/**
+ * The rail's tooltip (20.1): no arrow, its edge 13px from the button (4px past the rail),
+ * and the dot between the label and the hint set a little apart.
+ */
+function RailTip({ label, hint, children }) {
+    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: children }), _jsxs(TooltipContent, { side: "right", sideOffset: 13, className: "py-[4.5px] [&>span:has(>svg)]:hidden", children: [label, hint && (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "px-[2.5px]", children: ' · ' }), hint] }))] })] }));
+}
+export const Sidebar = React.forwardRef(function Sidebar({ rail = false, className, children, ...props }, ref) {
+    return (_jsx(RailContext.Provider, { value: rail, children: _jsx("nav", { ref: ref, "aria-label": "Main", "data-pane": "sidebar", "data-rail": rail || undefined, className: cn('flex h-full shrink-0 flex-col bg-sidebar px-2 transition-[width] duration-200 ease-rise', rail ? 'w-[52px] items-center' : 'w-60', className), ...props, children: children }) }));
+});
+Sidebar.displayName = 'Sidebar';
+export const SidebarHeader = React.forwardRef(function SidebarHeader({ rail: railProp, href = '/', label = 'Go to Home', logo, mark, onToggle, className, ...props }, ref) {
+    const rail = useRail(railProp);
+    if (rail) {
+        return (_jsx("div", { ref: ref, className: cn('flex h-[60px] shrink-0 items-center justify-center', className), ...props, children: onToggle ? (_jsx(RailTip, { label: "Expand the sidebar", children: _jsxs("button", { type: "button", onClick: onToggle, "aria-label": "Expand the sidebar", className: "group/mark inline-flex size-9 items-center justify-center rounded-md text-subtle-foreground outline-none hover:bg-sidebar-hover hover:text-foreground focus-visible:shadow-[var(--focus-ring)]", children: [_jsx("span", { className: "group-hover/mark:hidden group-focus-visible/mark:hidden", children: mark ?? _jsx(SoleMark, { size: 20 }) }), _jsx(PanelLeft, { size: 16, strokeWidth: 1.8, "aria-hidden": "true", className: "hidden group-hover/mark:block group-focus-visible/mark:block" })] }) })) : ((mark ?? _jsx(SoleMark, { size: 20 }))) }));
+    }
+    return (_jsxs("div", { ref: ref, className: cn('flex h-[66px] shrink-0 items-center justify-between pt-3 pl-2', className), ...props, children: [_jsx(SoleLink, { href: href, "aria-label": label, className: "rounded-md outline-none focus-visible:shadow-[var(--focus-ring)]", children: logo ?? _jsx(SoleLockup, { size: 20 }) }), onToggle && (_jsx(RailTip, { label: "Collapse the sidebar", children: _jsx("button", { type: "button", onClick: onToggle, "aria-label": "Collapse the sidebar", className: "inline-flex size-7 items-center justify-center rounded-md text-subtle-foreground outline-none hover:bg-sidebar-hover hover:text-foreground focus-visible:shadow-[var(--focus-ring)]", children: _jsx(PanelLeft, { size: 16, strokeWidth: 1.8, "aria-hidden": "true" }) }) }))] }));
+});
+SidebarHeader.displayName = 'SidebarHeader';
+/** A stack of rows: 2px apart, or 4px apart and centred in the rail. */
+export const SidebarSection = React.forwardRef(function SidebarSection({ rail: railProp, className, ...props }, ref) {
+    const rail = useRail(railProp);
+    return _jsx("div", { ref: ref, className: cn('flex w-full flex-col', rail ? 'items-center gap-1' : 'gap-0.5', className), ...props });
+});
+SidebarSection.displayName = 'SidebarSection';
+/** The middle of the sidebar: it takes the spare height and scrolls when the rows do not fit. */
+export const SidebarContent = React.forwardRef(function SidebarContent({ rail: railProp, className, ...props }, ref) {
+    const rail = useRail(railProp);
+    return _jsx("div", { ref: ref, className: cn('flex min-h-0 w-full flex-1 flex-col overflow-x-hidden overflow-y-auto', rail ? 'mt-4 items-center' : 'mt-3', className), ...props });
+});
+SidebarContent.displayName = 'SidebarContent';
+/** The bottom of the sidebar (settings, the user row), pinned under the scrolling middle. */
+export const SidebarFooter = React.forwardRef(function SidebarFooter({ rail: railProp, className, ...props }, ref) {
+    const rail = useRail(railProp);
+    return _jsx("div", { ref: ref, className: cn('flex w-full shrink-0 flex-col pt-2', rail ? 'items-center gap-1 pb-4' : 'gap-0.5 pb-5', className), ...props });
+});
+SidebarFooter.displayName = 'SidebarFooter';
+export const SidebarItem = React.forwardRef(function SidebarItem({ href, icon, label, active = false, badge, shortcut, hint, trailing, rail: railProp, className, ...props }, ref) {
+    const rail = useRail(railProp);
+    const classes = cn(itemClass(active), 'group/nav relative', rail && railClass, className);
+    const common = {
+        'aria-current': active ? 'page' : undefined,
+        'aria-label': rail ? (badge ? `${label}, ${badge.label}` : label) : undefined,
+        className: classes,
+        ...props,
+    };
+    const inner = (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: cn('flex shrink-0 items-center justify-center [&>svg]:size-4', active ? '[&>svg]:[stroke-width:2.1]' : '[&>svg]:[stroke-width:1.8]'), children: icon }), !rail && _jsx("span", { className: "flex-1 truncate text-left", children: label }), !rail && badge && _jsx(CountBadge, { label: badge.label, children: badge.text }), !rail && shortcut && !badge && _jsx(Kbd, { keys: shortcut, className: "opacity-0 transition-opacity group-hover/nav:opacity-100" }), !rail && trailing] }));
+    // One ref type for both elements; each branch narrows it to the element it renders.
+    const row = href ? (_jsx(SoleLink, { ref: ref, href: href, ...common, children: inner })) : (_jsx("button", { ref: ref, type: "button", ...common, children: inner }));
+    if (!rail)
+        return row;
+    // Counts are words in the tooltip, never a dot on the icon (brand-and-ux 4.3).
+    return (_jsx(RailTip, { label: label, hint: hint ?? (shortcut ? keysText(shortcut, ' ') : badge?.label), children: row }));
+});
+SidebarItem.displayName = 'SidebarItem';
+/** A labelled, collapsible list of rows. In the rail the label becomes a short rule and the rows always show. */
+export const SidebarGroup = React.forwardRef(function SidebarGroup({ label, open: openProp, defaultOpen = true, onOpenChange, rail: railProp, className, children, ...props }, ref) {
+    const rail = useRail(railProp);
+    const [own, setOwn] = React.useState(defaultOpen);
+    const open = openProp ?? own;
+    const toggle = () => {
+        if (openProp === undefined)
+            setOwn(!open);
+        onOpenChange?.(!open);
+    };
+    return (_jsxs("div", { ref: ref, className: cn('flex flex-col', rail ? 'mt-1 items-center gap-1' : 'gap-0.5', className), ...props, children: [rail ? (_jsx("div", { className: "my-1 h-px w-6 bg-border", "aria-hidden": "true" })) : (_jsxs("button", { type: "button", onClick: toggle, "aria-expanded": open, className: "mt-4 flex h-7 items-center justify-between rounded-md px-2 text-micro text-subtle-foreground outline-none hover:text-foreground focus-visible:shadow-[var(--focus-ring)]", children: [label, _jsx(ChevronDown, { size: 14, "aria-hidden": "true", className: cn('text-faint transition-transform duration-200', !open && '-rotate-90') })] })), (open || rail) && children] }));
+});
+SidebarGroup.displayName = 'SidebarGroup';
+/** The user row and its menu (20.4-user-menu.png). */
+export const SidebarUser = React.forwardRef(function SidebarUser({ person, meta, rail: railProp, className, children, ...props }, ref) {
+    const rail = useRail(railProp);
+    const name = personName(person);
+    const trigger = (_jsxs(DropdownMenuTrigger, { ref: ref, "aria-label": `${name}, open the menu`, className: cn('flex w-full min-w-0 items-center gap-2 rounded-md px-2 py-1 text-left outline-none transition-colors duration-[120ms] hover:bg-sidebar-hover focus-visible:shadow-[var(--focus-ring)]', 
+        // The rail's avatar sits 4px closer to the row below it than the rows above it do (20.1).
+        rail && cn(railClass, '-mt-1'), className), ...props, children: [_jsx(Avatar, { person: person, size: 24 }), !rail && (_jsxs(_Fragment, { children: [_jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "truncate text-body leading-4 font-medium text-foreground", children: name }), meta && _jsx("span", { className: "truncate text-label leading-4 font-normal text-subtle-foreground", children: meta })] }), _jsx(ChevronsUpDown, { size: 14, "aria-hidden": "true", className: "shrink-0 text-subtle-foreground" })] }))] }));
+    return (_jsxs(DropdownMenu, { children: [rail ? _jsx(RailTip, { label: name, children: trigger }) : trigger, _jsxs(DropdownMenuContent, { side: rail ? 'right' : 'top', align: rail ? 'end' : 'start', sideOffset: rail ? 8 : 0, className: "w-[223px]", children: [_jsx(DropdownMenuLabel, { className: "truncate text-micro text-subtle-foreground", children: name }), children] })] }));
+});
+SidebarUser.displayName = 'SidebarUser';
+/** The Search field that opens the command palette. It is a button: the palette has the real input. */
+export const SidebarSearch = React.forwardRef(function SidebarSearch({ rail: railProp, className, ...props }, ref) {
+    const rail = useRail(railProp);
+    const button = (_jsxs("button", { ref: ref, type: "button", "aria-label": rail ? 'Search' : undefined, "aria-keyshortcuts": "Meta+K Control+K", className: cn(rail
+            ? cn(itemClass(false), railClass)
+            : 'flex h-8 w-full items-center gap-2 rounded-lg border border-border bg-card px-[7px] text-body text-subtle-foreground shadow-xs outline-none transition-colors duration-[120ms] hover:border-input hover:text-muted-foreground focus-visible:shadow-[var(--focus-ring)]', className), ...props, children: [_jsx(Search, { size: rail ? 16 : 14, strokeWidth: 1.8, "aria-hidden": "true", className: "shrink-0" }), !rail && (_jsxs(_Fragment, { children: [_jsx("span", { className: "flex-1 text-left", children: "Search" }), _jsx(Kbd, { keys: ['mod', 'K'] })] }))] }));
+    return rail ? (_jsx(RailTip, { label: "Search", hint: keysText(['mod', 'K'], ' '), children: button })) : (button);
+});
+SidebarSearch.displayName = 'SidebarSearch';

package/dist/components/sole/avatar.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { type SolePerson } from '../../lib/person.ts';
+export type AvatarSize = 16 | 20 | 24 | 32 | 40 | 48 | 64;
+export interface AvatarProps extends Omit<React.ComponentPropsWithoutRef<'span'>, 'children'> {
+    /** `null` or `undefined` draws a "?", for someone who has gone. A bot (`isBot`) draws the bot icon. */
+    person: SolePerson | null | undefined;
+    size?: AvatarSize;
+    /** Set when the avatar stands alone, so screen readers hear the name. */
+    label?: boolean;
+}
+export declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;
+export interface AvatarStackProps extends Omit<React.ComponentPropsWithoutRef<'span'>, 'children'> {
+    people: SolePerson[];
+    /** How many avatars to show before "+n". */
+    max?: number;
+    size?: AvatarSize;
+}
+/** Up to `max` avatars overlapping, then "+n". */
+export declare const AvatarStack: React.ForwardRefExoticComponent<AvatarStackProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/sole/avatar.js

@@ -0,0 +1,37 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { Bot } from 'lucide-react';
+import { cn } from '../../lib/cn.js';
+import { avatarColour } from '../../lib/colour.js';
+import { initials, personName } from '../../lib/person.js';
+/** The picture in the circle, or the initials when there is none or it did not load. */
+function Face({ url, name }) {
+    // The address that failed, so a new picture (a new address) gets its own try.
+    const [failed, setFailed] = React.useState(null);
+    if (url && failed !== url) {
+        return _jsx("img", { src: url, alt: "", draggable: false, decoding: "async", referrerPolicy: "no-referrer", onError: () => setFailed(url), className: "size-full rounded-full object-cover" });
+    }
+    return _jsx(_Fragment, { children: initials(name) });
+}
+export const Avatar = React.forwardRef(function Avatar({ person, size = 20, label, className, style, ...props }, ref) {
+    const name = personName(person);
+    const box = { width: size, height: size, fontSize: Math.round(size * 0.36) };
+    const a11y = label ? { role: 'img', 'aria-label': name, title: name } : { 'aria-hidden': true };
+    if (!person || person.isBot) {
+        return (_jsx("span", { ref: ref, ...a11y, style: { ...box, ...style }, className: cn('inline-flex shrink-0 items-center justify-center rounded-full border border-border bg-neutral-soft text-subtle-foreground select-none', className), ...props, children: person?.isBot ? _jsx(Bot, { size: Math.round(size * 0.6), strokeWidth: 1.8, "aria-hidden": "true" }) : '?' }));
+    }
+    const colour = avatarColour(person.id);
+    return (_jsx("span", { ref: ref, ...a11y, "data-colour": colour, style: { ...box, backgroundColor: `${colour}18`, borderColor: `${colour}33`, color: colour, ...style }, className: cn('inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full border leading-none font-bold tracking-tight select-none', className), ...props, children: _jsx(Face, { url: person.avatarUrl, name: name }) }));
+});
+Avatar.displayName = 'Avatar';
+/** Up to `max` avatars overlapping, then "+n". */
+export const AvatarStack = React.forwardRef(function AvatarStack({ people, max = 2, size = 20, className, ...props }, ref) {
+    if (!people.length)
+        return null;
+    const shown = people.slice(0, max);
+    const extra = people.length - shown.length;
+    const names = people.map((p) => personName(p)).join(', ');
+    return (_jsxs("span", { ref: ref, role: "img", "aria-label": names, title: names, className: cn('inline-flex shrink-0 items-center', className), ...props, children: [shown.map((p, i) => (_jsx(Avatar, { person: p, size: size, className: cn('ring-2 ring-card', i > 0 && '-ml-1') }, p.id))), extra > 0 && (_jsxs("span", { style: { height: size, minWidth: size, fontSize: Math.round(size * 0.45) }, className: "-ml-1 inline-flex items-center justify-center rounded-full border border-border bg-neutral-soft px-1 font-semibold text-neutral-text ring-2 ring-card", children: ["+", extra] }))] }));
+});
+AvatarStack.displayName = 'AvatarStack';

package/dist/components/sole/banner.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { type LucideIcon } from 'lucide-react';
+export type BannerTone = 'danger' | 'warning' | 'success' | 'info';
+export interface BannerProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'role'> {
+    tone: BannerTone;
+    /** Overrides the tone's icon, e.g. CalendarX for a review that is due. */
+    icon?: LucideIcon;
+    /** Buttons on the right, 32px: the quiet one first, the main action last. */
+    actions?: React.ReactNode;
+    children: React.ReactNode;
+    /** Defaults to alert for danger and status otherwise. */
+    role?: 'alert' | 'status';
+}
+export declare const Banner: React.ForwardRefExoticComponent<BannerProps & React.RefAttributes<HTMLDivElement>>;
+export interface InlineErrorProps extends React.ComponentPropsWithoutRef<'p'> {
+    children: React.ReactNode;
+}
+/** One line under a field when something failed: "That email or password is not right." */
+export declare const InlineError: React.ForwardRefExoticComponent<InlineErrorProps & React.RefAttributes<HTMLParagraphElement>>;
+export interface InlineSuccessProps extends React.ComponentPropsWithoutRef<'p'> {
+    children: React.ReactNode;
+}
+/** One line after an action that worked: "The key works. Gemini answered in 1.2 s." */
+export declare const InlineSuccess: React.ForwardRefExoticComponent<InlineSuccessProps & React.RefAttributes<HTMLParagraphElement>>;

package/dist/components/sole/banner.js

@@ -0,0 +1,27 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { CircleAlert, CircleCheck, Info, TriangleAlert } from 'lucide-react';
+import { cn } from '../../lib/cn.js';
+const TONES = {
+    danger: { box: 'border-danger-border bg-danger-soft text-danger-text', icon: 'text-danger-text', Icon: CircleAlert },
+    warning: { box: 'border-warning-border bg-warning-soft text-warning-text', icon: 'text-warning-text', Icon: TriangleAlert },
+    success: { box: 'border-success-border bg-success-soft text-success-text', icon: 'text-success', Icon: CircleCheck },
+    info: { box: 'border-brand/30 bg-accent text-accent-foreground', icon: 'text-accent-foreground', Icon: Info },
+};
+export const Banner = React.forwardRef(function Banner({ tone, icon: IconProp, actions, children, role, className, ...props }, ref) {
+    const t = TONES[tone];
+    const Icon = IconProp ?? t.Icon;
+    return (_jsxs("div", { ref: ref, role: role ?? (tone === 'danger' ? 'alert' : 'status'), "data-banner": tone, className: cn('flex items-center rounded-lg border py-2 pr-3 pl-2.5', t.box, className), ...props, children: [_jsx(Icon, { size: 16, strokeWidth: 1.8, "aria-hidden": "true", className: cn('mr-2.5 shrink-0', t.icon) }), _jsx("div", { className: "min-w-0 flex-1 py-px text-body", children: children }), actions && _jsx("div", { className: "ml-3 flex shrink-0 items-center gap-2", children: actions })] }));
+});
+Banner.displayName = 'Banner';
+/** One line under a field when something failed: "That email or password is not right." */
+export const InlineError = React.forwardRef(function InlineError({ children, className, ...props }, ref) {
+    return (_jsxs("p", { ref: ref, role: "alert", className: cn('flex items-start gap-1.5 text-label text-danger-text', className), ...props, children: [_jsx(CircleAlert, { size: 14, strokeWidth: 1.8, "aria-hidden": "true", className: "mt-px shrink-0" }), _jsx("span", { className: "min-w-0", children: children })] }));
+});
+InlineError.displayName = 'InlineError';
+/** One line after an action that worked: "The key works. Gemini answered in 1.2 s." */
+export const InlineSuccess = React.forwardRef(function InlineSuccess({ children, className, ...props }, ref) {
+    return (_jsxs("p", { ref: ref, role: "status", className: cn('flex items-start gap-1.5 text-label text-success-text', className), ...props, children: [_jsx(CircleCheck, { size: 14, strokeWidth: 1.8, "aria-hidden": "true", className: "mt-px shrink-0 text-success" }), _jsx("span", { className: "min-w-0", children: children })] }));
+});
+InlineSuccess.displayName = 'InlineSuccess';

package/dist/components/sole/column-header.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+/**
+ * Column header for kanban (50.3): an icon, 13/600 name, count, and a + on the right.
+ * The icon is the caller's (HQ passes its state icon), so the part knows no domain.
+ */
+export declare const ColumnHeader: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children"> & {
+    name: string;
+    count?: number;
+    /** Before the name: a 16px decorative icon. */
+    icon?: React.ReactNode;
+    /** Shows the + button when given. */
+    onAdd?: () => void;
+    /** The + button's name for screen readers and its tooltip. Defaults to "Add to <name>". */
+    addLabel?: string;
+} & React.RefAttributes<HTMLDivElement>>;

package/dist/components/sole/column-header.js

@@ -0,0 +1,15 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { Plus } from 'lucide-react';
+import { cn } from '../../lib/cn.js';
+import { Button } from '../ui/button.js';
+/**
+ * Column header for kanban (50.3): an icon, 13/600 name, count, and a + on the right.
+ * The icon is the caller's (HQ passes its state icon), so the part knows no domain.
+ */
+export const ColumnHeader = React.forwardRef(function ColumnHeader({ name, count, icon, onAdd, addLabel, className, ...props }, ref) {
+    const label = addLabel ?? `Add to ${name}`;
+    return (_jsxs("div", { ref: ref, className: cn('flex h-8 min-w-0 items-center gap-2 pr-0.5 pl-1', className), ...props, children: [icon, _jsx("h3", { className: "truncate text-body font-semibold text-foreground", children: name }), count !== undefined && _jsx("span", { className: "tnum text-label font-normal text-subtle-foreground", children: count }), onAdd && (_jsx(Button, { variant: "ghost", size: "icon-xs", onClick: onAdd, "aria-label": label, title: label, className: "ml-auto text-faint hover:text-foreground", children: _jsx(Plus, { "aria-hidden": "true", className: "size-3.5" }) }))] }));
+});
+ColumnHeader.displayName = 'ColumnHeader';

package/dist/components/sole/copy-field.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+export interface CopyFieldProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'children'> {
+    value: string;
+    /** A password shown once: monospace, 15px. */
+    secret?: boolean;
+    /** What is copied, for screen readers: "Temporary password", "Sign-up link". */
+    label: string;
+    onCopied?: () => void;
+}
+export declare const CopyField: React.ForwardRefExoticComponent<CopyFieldProps & React.RefAttributes<HTMLDivElement>>;