From fa197889041c559ee67fafbc4f3c6e021432532c Mon Sep 17 00:00:00 2001 From: mindsers Date: Fri, 13 Nov 2026 14:28:44 +0100 Subject: [PATCH 1/3] feat(ui): the app shell pieces (ui 0.11.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A second app needs the shell the first one built, so its router-free half moves here: labels, icons and links come in as props (`renderLink`), and nothing imports a router, a message catalogue or an icon set. - SidebarFrame, NavGroup, NavItem: the quiet column, its groups and entries; `current` marks the page for the eye and for screen readers, `shortcut` shows on hover and focus. - TopbarRow, Breadcrumb: the 48 px bar, the trail ending with the page itself, the actions on the right. Positioning and phone stacking stay the app shell's (pass them through `className`). - PageTitle: the title row with its facts and the controls that change what the page shows. - QuickViews: the segmented control from the tablet up, scrolling chips on a phone. - FilterButton, FilterChipBar: the one « Filtres » button with its count, and the active filters as chips. The popover stays the app's; the button passes trigger props through, refs included. - PaginationBar, EmptyState, ErrorState, AuthFrame: previous / next with the position, the empty list, an error in the page's place, the bare page outside the shell. --- ui/README.md | 9 ++ ui/package.json | 4 +- ui/src/auth-frame.tsx | 53 +++++++++ ui/src/empty-state.tsx | 31 ++++++ ui/src/error-state.tsx | 37 +++++++ ui/src/filters.tsx | 153 ++++++++++++++++++++++++++ ui/src/index.ts | 31 ++++++ ui/src/page-title.tsx | 47 ++++++++ ui/src/pagination-bar.tsx | 79 ++++++++++++++ ui/src/quick-views.tsx | 85 +++++++++++++++ ui/src/sidebar-nav.tsx | 98 +++++++++++++++++ ui/src/topbar.tsx | 110 +++++++++++++++++++ ui/test/components.test.tsx | 211 ++++++++++++++++++++++++++++++++++++ 13 files changed, 946 insertions(+), 2 deletions(-) create mode 100644 ui/src/auth-frame.tsx create mode 100644 ui/src/empty-state.tsx create mode 100644 ui/src/error-state.tsx create mode 100644 ui/src/filters.tsx create mode 100644 ui/src/page-title.tsx create mode 100644 ui/src/pagination-bar.tsx create mode 100644 ui/src/quick-views.tsx create mode 100644 ui/src/sidebar-nav.tsx create mode 100644 ui/src/topbar.tsx diff --git a/ui/README.md b/ui/README.md index 74a9359..40f3db1 100644 --- a/ui/README.md +++ b/ui/README.md @@ -58,6 +58,15 @@ Tell Tailwind v4 to read the classes the components use, next to the tokens impo | `MapCaption`, `MapCard` | A line about the map (top left); a picked place's card (corner, or full width below 1280) | | `MapAttribution` | The data credit, always visible bottom right (pass `MAP_ATTRIBUTION` from the tokens) | | `MapStatus` | Loading or failed tiles, in the middle of the map's frame | +| `SidebarFrame`, `NavGroup`, `NavItem`| The quiet column on the left: header, groups under their labels, entries with an icon and a shortcut on hover; links through `renderLink` | +| `TopbarRow`, `Breadcrumb` | The 48 px bar at the top of a page: the trail ending with the page itself, the page’s actions on the right | +| `PageTitle` | The title row: the h1, its facts and the controls that change what the page shows | +| `QuickViews` | A list’s quick views with their counts: the segmented control from the tablet up, chips that scroll on a phone | +| `FilterButton`, `FilterChipBar`| The one « Filtres » button with its count (the popover stays the app’s), and the active filters as chips | +| `PaginationBar` | Under a long list: where the reader is, and previous / next | +| `EmptyState` | A list with nothing in it: one plain sentence and, when the reader can act, the action | +| `ErrorState` | An error drawn where the page would have been: code, title, what to do, the ways on | +| `AuthFrame` | The bare page outside an app’s shell: one narrow column with an emblem, the action as title, a footer | | `Mark`, `Lockup` | The Unitae mark, alone or with the wordmark | Helpers: `seriesColor(i)` (categorical colours in order, folded past eight), `chartMuted`, `chartContext`, diff --git a/ui/package.json b/ui/package.json index faaf8f6..74097a9 100644 --- a/ui/package.json +++ b/ui/package.json @@ -1,7 +1,7 @@ { "name": "@unitae/ui", - "version": "0.10.0", - "description": "Unitae UI components: stat tiles, chart kit (with table twins), status, avatars, selection bar, segmented control, form sections, save bar, panels, section headings, map pieces and the brand mark. Built on @unitae/tokens.", + "version": "0.11.0", + "description": "Unitae UI components: stat tiles, chart kit (with table twins), status, avatars, selection bar, segmented control, form sections, save bar, panels, section headings, map pieces, the app shell pieces (sidebar, top bar, title row, quick views, filters, pagination, empty and error states, sign-in frame) and the brand mark. Built on @unitae/tokens.", "license": "MIT", "type": "module", "repository": { diff --git a/ui/src/auth-frame.tsx b/ui/src/auth-frame.tsx new file mode 100644 index 0000000..a9e539d --- /dev/null +++ b/ui/src/auth-frame.tsx @@ -0,0 +1,53 @@ +import type { ReactNode } from 'react' +import { cn } from './utils.ts' + +export interface AuthFrameProps { + /** Opens the column: a monogram, the `Lockup`, or a quiet icon tile on a page that reports rather than asks. */ + emblem?: ReactNode + /** A line above the title, e.g. the congregation's name or « Erreur 404 ». */ + eyebrow?: ReactNode + /** The page's action, e.g. « Se connecter ». */ + title: ReactNode + /** What the page says under its title. */ + description?: ReactNode + /** A slightly wider column, for a page that is mostly reading. */ + wide?: boolean + /** Closes the page: the mark, the privacy link, a language switch. */ + footer?: ReactNode + children?: ReactNode + className?: string +} + +/** + * The frame of every page outside an app's shell — signing in, a link sent, a payment, an error the app could not + * frame: the bare page, one narrow column in the middle, no card. + */ +export function AuthFrame({ + emblem, + eyebrow, + title, + description, + wide = false, + footer, + children, + className, +}: AuthFrameProps) { + return ( +
+
+
+
+ {emblem} +
+ {eyebrow != null &&

{eyebrow}

} +

{title}

+
+ {description != null &&

{description}

} +
+ {children} +
+
+ {footer != null &&
{footer}
} +
+ ) +} diff --git a/ui/src/empty-state.tsx b/ui/src/empty-state.tsx new file mode 100644 index 0000000..0a6ae84 --- /dev/null +++ b/ui/src/empty-state.tsx @@ -0,0 +1,31 @@ +import type { ReactNode } from 'react' +import { cn } from './utils.ts' + +export interface EmptyStateProps { + /** A quiet icon in a neutral tile; no illustration. */ + icon?: ReactNode + /** One plain sentence. */ + title: ReactNode + description?: ReactNode + /** When the reader can act: the action, usually one button. */ + action?: ReactNode + className?: string +} + +/** What a list or a page shows with nothing in it: one plain sentence and, when the reader can act, the action. */ +export function EmptyState({ icon, title, description, action, className }: EmptyStateProps) { + return ( +
+ {icon != null && ( +
+ {icon} +
+ )} +
+

{title}

+ {description != null &&

{description}

} +
+ {action != null &&
{action}
} +
+ ) +} diff --git a/ui/src/error-state.tsx b/ui/src/error-state.tsx new file mode 100644 index 0000000..1f0372e --- /dev/null +++ b/ui/src/error-state.tsx @@ -0,0 +1,37 @@ +import type { ReactNode } from 'react' +import { cn } from './utils.ts' + +export interface ErrorStateProps { + /** A quiet icon in a neutral tile, e.g. a magnifier for « introuvable ». */ + icon?: ReactNode + /** Above the title, e.g. « Erreur 404 ». */ + code?: ReactNode + title: ReactNode + /** What happened and what to do, in plain words. */ + description?: ReactNode + /** The ways on: one filled button (a retry, or the most useful way back), the others quieter. */ + actions?: ReactNode + /** Below the actions, e.g. the technical details of a server error in a `
`. */ + details?: ReactNode + className?: string +} + +/** An error drawn where the page would have been, so the shell around it stays and the way back is one click. */ +export function ErrorState({ icon, code, title, description, actions, details, className }: ErrorStateProps) { + return ( +
+ {icon != null && ( + + {icon} + + )} +
+ {code != null &&

{code}

} +

{title}

+
+ {description != null &&

{description}

} + {actions != null &&
{actions}
} + {details} +
+ ) +} diff --git a/ui/src/filters.tsx b/ui/src/filters.tsx new file mode 100644 index 0000000..015a0f9 --- /dev/null +++ b/ui/src/filters.tsx @@ -0,0 +1,153 @@ +import type { ComponentProps, ReactNode } from 'react' +import { cn } from './utils.ts' + +export interface FilterButtonProps extends Omit, 'children'> { + /** The button's text, e.g. « Filtres ». */ + label: string + /** How many filters are on; nothing shows at 0. */ + count?: number + /** The accessible name while filters are on, e.g. « Filtres, 2 actifs ». */ + activeLabel?: string +} + +/** + * The one « Filtres » button of a list's toolbar, saying how many filters are on. The popover it opens is the app's + * (it passes the trigger props through, refs included, so a Radix `asChild` trigger works). + */ +export function FilterButton({ + label, + count = 0, + activeLabel, + className, + type = 'button', + ...props +}: FilterButtonProps) { + return ( + + ) +} + +export interface FilterChipItem { + /** Identifies the chip, e.g. the query parameter its × clears. */ + key: string + /** The filter's name, e.g. « Groupe ». */ + label: string + /** What it is set to, e.g. « Nord ». */ + value: string + /** Where its × leads (the address without this filter), rendered through `renderLink`; else `onRemove`. */ + removeHref?: string + onRemove?: () => void +} + +export interface FilterChipLinkProps { + href: string + className: string + 'aria-label'?: string + children: ReactNode +} + +export interface FilterChipBarProps { + chips: FilterChipItem[] + /** Names the region for screen readers, e.g. « Filtres actifs ». */ + 'aria-label': string + /** The × button's accessible name for a chip, e.g. `c => \`Retirer ${c.label} : ${c.value}\``. */ + removeLabel: (chip: FilterChipItem) => string + /** The text of the link that clears them all, e.g. « Effacer les filtres ». */ + clearLabel: string + clearHref?: string + onClear?: () => void + /** Renders a link with the app's router link. */ + renderLink?: (props: FilterChipLinkProps) => ReactNode + className?: string +} + +const removeClass = + 'inline-flex size-6 items-center justify-center rounded-full text-muted-foreground outline-none transition-colors duration-(--u-duration-fast) hover:bg-hover hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring' +const clearClass = 'text-sm text-brand-text underline-offset-4 hover:underline' + +function Cross() { + return ( + + ) +} + +/** + * The active filters under a list's toolbar, one chip each (« Groupe : Nord »), and the link that clears them all. + * Only a chip's × removes its filter, so a click on the label never drops one by mistake. Nothing shows without one. + */ +export function FilterChipBar({ + chips, + removeLabel, + clearLabel, + clearHref, + onClear, + renderLink, + className, + ...rest +}: FilterChipBarProps) { + if (chips.length === 0) return null + const link = (props: FilterChipLinkProps) => (renderLink ? renderLink(props) : ) + return ( +
+ {chips.map((chip) => ( + + {chip.label} : + {chip.value} + {chip.removeHref != null ? ( + link({ + href: chip.removeHref, + className: removeClass, + 'aria-label': removeLabel(chip), + children: , + }) + ) : ( + + )} + + ))} + {clearHref != null ? ( + link({ href: clearHref, className: clearClass, children: clearLabel }) + ) : ( + + )} +
+ ) +} diff --git a/ui/src/index.ts b/ui/src/index.ts index 6d3166d..1457e98 100644 --- a/ui/src/index.ts +++ b/ui/src/index.ts @@ -1,3 +1,4 @@ +export { AuthFrame, type AuthFrameProps } from './auth-frame.tsx' export { Avatar, type AvatarProps, initials } from './avatar.tsx' export { BarList, @@ -29,7 +30,17 @@ export { } from './charts.tsx' export { DateChip, type DateChipProps } from './date-chip.tsx' export { DateField, type DateFieldLabels, type DateFieldProps } from './date-field.tsx' +export { EmptyState, type EmptyStateProps } from './empty-state.tsx' +export { ErrorState, type ErrorStateProps } from './error-state.tsx' export { type Fact, FactList, type FactListProps } from './fact-list.tsx' +export { + FilterButton, + type FilterButtonProps, + FilterChipBar, + type FilterChipBarProps, + type FilterChipItem, + type FilterChipLinkProps, +} from './filters.tsx' export { FormSection, type FormSectionProps } from './form-section.tsx' export { MapAttribution, @@ -54,6 +65,8 @@ export { type MapStatusProps, } from './map.tsx' export { Lockup, type LockupProps, Mark, type MarkProps } from './mark.tsx' +export { PageTitle, type PageTitleProps } from './page-title.tsx' +export { PaginationBar, type PaginationBarProps } from './pagination-bar.tsx' export { Panel, type PanelProps } from './panel.tsx' export { type PeriodLinkProps, @@ -63,11 +76,21 @@ export { } from './period-stepper.tsx' export { ProgressBar, type ProgressBarProps, type ProgressTone } from './progress-bar.tsx' export { ProgressRing, type ProgressRingProps } from './progress-ring.tsx' +export { type QuickView, QuickViews, type QuickViewsProps } from './quick-views.tsx' export { SaveBar, type SaveBarProps } from './save-bar.tsx' export { SectionHeading, type SectionHeadingProps } from './section-heading.tsx' export { SegmentedControl, type SegmentedControlProps, type SegmentedOption } from './segmented-control.tsx' export { SelectionBar, type SelectionBarProps } from './selection-bar.tsx' export { SidePanel, type SidePanelProps, type SidePanelWalk } from './side-panel.tsx' +export { + NavGroup, + type NavGroupProps, + NavItem, + type NavItemProps, + type NavLinkProps, + SidebarFrame, + type SidebarFrameProps, +} from './sidebar-nav.tsx' export { MetricStrip, type MetricStripProps, @@ -79,4 +102,12 @@ export { type StatTone, } from './stat-tile.tsx' export { Kbd, Status, StatusIcon, type StatusProps, type StatusTone, Tag, type TagProps } from './status.tsx' +export { + Breadcrumb, + type BreadcrumbItem, + type BreadcrumbLinkProps, + type BreadcrumbProps, + TopbarRow, + type TopbarRowProps, +} from './topbar.tsx' export { chartContext, chartMuted, chartOther, cn, seriesColor, share } from './utils.ts' diff --git a/ui/src/page-title.tsx b/ui/src/page-title.tsx new file mode 100644 index 0000000..ace8e17 --- /dev/null +++ b/ui/src/page-title.tsx @@ -0,0 +1,47 @@ +import type { ReactNode } from 'react' +import { cn } from './utils.ts' + +export interface PageTitleProps { + title: ReactNode + /** Right after the title, e.g. a count or a `Tag`. */ + titleBadge?: ReactNode + subtitle?: ReactNode + /** A line of facts under the subtitle, e.g. « Territoire 14 · 14 foyers · 3 entrées ». */ + meta?: ReactNode + /** What the page is about, drawn in a quiet tile before the title (a building, a congregation…). */ + icon?: ReactNode + /** Controls over what the page shows (a filter, a period) on the title's row. Actions go in the top bar. */ + controls?: ReactNode + className?: string +} + +/** The page's title row: the h1 with its facts, and the controls that change what the page shows. */ +export function PageTitle({ title, titleBadge, subtitle, meta, icon, controls, className }: PageTitleProps) { + const heading = ( +
+ {icon != null && ( + + {icon} + + )} +
+
+

{title}

+ {titleBadge} +
+ {subtitle != null &&

{subtitle}

} + {meta != null && ( +
{meta}
+ )} +
+
+ ) + if (controls == null) return
{heading}
+ return ( +
+ {heading} + {/* On a phone the controls wrap under each other on a row of their own, rather than run past the edge. */} +
{controls}
+
+ ) +} diff --git a/ui/src/pagination-bar.tsx b/ui/src/pagination-bar.tsx new file mode 100644 index 0000000..7a812ff --- /dev/null +++ b/ui/src/pagination-bar.tsx @@ -0,0 +1,79 @@ +import type { ReactNode } from 'react' +import type { PeriodLinkProps, PeriodStep } from './period-stepper.tsx' +import { cn } from './utils.ts' + +export interface PaginationBarProps { + /** Where the reader is, e.g. « 1–25 sur 42 » or « Page 1 sur 2 ». */ + label: ReactNode + previous: PeriodStep + next: PeriodStep + /** Renders a step that has an `href` with the app's router link. */ + renderLink?: (props: PeriodLinkProps) => ReactNode + /** On the left, before the label: a page-size control, a total. */ + children?: ReactNode + className?: string +} + +const stepClass = + 'inline-flex size-8 flex-none items-center justify-center rounded-md border border-input bg-surface text-muted-foreground outline-none transition-colors duration-(--u-duration-fast) hover:bg-hover hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring' + +function Chevron({ direction }: { direction: 'left' | 'right' }) { + return ( + + ) +} + +function Step({ + step, + direction, + renderLink, +}: { + step: PeriodStep + direction: 'left' | 'right' + renderLink?: PaginationBarProps['renderLink'] +}) { + const icon = + if (step.disabled) { + return ( + + ) + } + if (step.href != null) { + const props = { href: step.href, className: stepClass, 'aria-label': step.label, children: icon } + return renderLink ? renderLink(props) :
+ } + return ( + + ) +} + +/** Under a long list: where the reader is, and the way to the previous and next page. */ +export function PaginationBar({ label, previous, next, renderLink, children, className }: PaginationBarProps) { + return ( +
+ {children} + {label} + + + +
+ ) +} diff --git a/ui/src/quick-views.tsx b/ui/src/quick-views.tsx new file mode 100644 index 0000000..7835ab0 --- /dev/null +++ b/ui/src/quick-views.tsx @@ -0,0 +1,85 @@ +import { SegmentedControl } from './segmented-control.tsx' +import { cn } from './utils.ts' + +export interface QuickView { + value: V + label: string + count: number +} + +export interface QuickViewsProps { + /** Names the group for screen readers. */ + label: string + views: QuickView[] + value: V + onChoose: (value: V) => void + /** `md` (the default) is as tall as the search field and the buttons beside it; `sm` sits in a section heading. */ + size?: 'sm' | 'md' + className?: string +} + +/** + * A list's quick views, each with how many items it holds. From the tablet up, the segmented control, the count faint + * after the label (two to five views, as the control takes). On a phone its equal segments no longer fit, so the views + * become a row of chips that scrolls sideways. + */ +export function QuickViews({ + label, + views, + value, + onChoose, + size = 'md', + className, +}: QuickViewsProps) { + return ( + <> + ({ + value: view.value, + label: ( + + {view.label} + + + ), + }))} + /> +
+ {label} + {views.map((view) => { + const pressed = view.value === value + return ( + + ) + })} +
+ + ) +} + +function Count({ value }: { value: number }) { + return {value} +} diff --git a/ui/src/sidebar-nav.tsx b/ui/src/sidebar-nav.tsx new file mode 100644 index 0000000..64271fe --- /dev/null +++ b/ui/src/sidebar-nav.tsx @@ -0,0 +1,98 @@ +import type { ReactNode } from 'react' +import { Kbd } from './status.tsx' +import { cn } from './utils.ts' + +export interface SidebarFrameProps { + /** Above the navigation: the product mark, a workspace menu, a search button. */ + header?: ReactNode + /** The navigation itself, usually a `