@santi020k/lumen 3.0.0 → 4.0.0

package/templates/react/operational-records/src/lumen/operational-records.tsx

@@ -0,0 +1,92 @@
+import { useState } from 'react'
+
+import { Button, DataTable, type DataTableCell, type DataTableColumn, type DataTableRow, type DataTableSort, Dialog, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Stack } from '@santi020k/lumen-react'
+
+export interface OperationalRecordsRecipeProps {
+  columns: DataTableColumn[]
+  rows: DataTableRow[]
+  sort: DataTableSort | null
+  onSortChange: (sort: DataTableSort | null) => void
+  label: string
+  actionsLabel: string
+  editLabel: string
+  closeLabel: string
+  detailsLabel: string
+  expandLabel: string
+  collapseLabel: string
+}
+
+const recordText = (cell: DataTableCell): string => typeof cell === 'object' && cell !== null ?
+  String(cell.label ?? cell.value ?? '') :
+  String(cell ?? '')
+
+/** Manual sorting delegates requests and row order to the host. Stable IDs are required. */
+export const OperationalRecordsRecipe = ({
+  columns, rows, sort, onSortChange, label, actionsLabel, editLabel, closeLabel,
+  detailsLabel, expandLabel, collapseLabel
+}: OperationalRecordsRecipeProps) => {
+  const [active, setActive] = useState<DataTableRow | undefined>(undefined)
+
+  return (
+    <>
+      <Stack direction="horizontal" wrap gap="related">
+        {columns.filter(column => column.sortable).map(column => (
+          <Button
+            key={column.key}
+            variant="outline"
+            aria-pressed={sort?.key === column.key}
+            onClick={() => {
+              onSortChange({ key: column.key, direction: sort?.key === column.key && sort.direction === 'ascending' ? 'descending' : 'ascending' })
+            }}
+          >
+            {column.header}
+          </Button>
+        ))}
+      </Stack>
+      <DataTable
+        role="region"
+        tabIndex={0}
+        aria-label={label}
+        layout="records"
+        rows={rows}
+        columns={[...columns.map(column => ({ ...column, sortable: false })), { key: 'actions',
+          header: actionsLabel,
+          render: (_cell, row) => (
+            <DropdownMenu>
+              <DropdownMenuTrigger aria-label={`${actionsLabel}: ${recordText(row.name ?? row.id)}`}>{actionsLabel}</DropdownMenuTrigger>
+              <DropdownMenuContent>
+                <DropdownMenuItem onClick={() => {
+                  setActive(row)
+                }}
+                >
+                  {editLabel}
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          ) }]}
+        sortMode="manual"
+        sort={sort}
+        onSortChange={onSortChange}
+        expandLabel={expandLabel}
+        collapseLabel={collapseLabel}
+        detailsLabel={detailsLabel}
+        renderDetails={row => <p>{recordText(row.detail)}</p>}
+      />
+      <Dialog
+        open={active !== undefined}
+        onOpenChange={open => {
+          if (!open) setActive(undefined)
+        }}
+        aria-label={editLabel}
+      >
+        <p>{recordText(active?.name)}</p>
+        <Button onClick={() => {
+          setActive(undefined)
+        }}
+        >
+          {closeLabel}
+        </Button>
+      </Dialog>
+    </>
+  )
+}

package/templates/react/page-header/src/lumen/page-header.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react'
+
+import { Badge, Breadcrumb, Link, Stack, Typography } from '@santi020k/lumen-react'
+
+export interface PageHeaderRecipeProps {
+  actions?: ReactNode
+  actionsLabel?: string
+  breadcrumbLabel?: string
+  breadcrumbs?: readonly { href: string, label: string }[]
+  description?: string
+  headingId: string
+  status?: string
+  title: string
+}
+
+const emptyBreadcrumbs: NonNullable<PageHeaderRecipeProps['breadcrumbs']> = []
+
+export const PageHeaderRecipe = ({ actions, actionsLabel = 'Page actions', breadcrumbLabel = 'Breadcrumb', breadcrumbs = emptyBreadcrumbs, description, headingId, status, title }: PageHeaderRecipeProps) => (
+  <header aria-labelledby={headingId}>
+    <Stack gap="group">
+      {breadcrumbs.length > 0 && (
+        <Breadcrumb aria-label={breadcrumbLabel}>
+          <ol>
+            {breadcrumbs.map(item => <li key={item.href}><Link href={item.href}>{item.label}</Link></li>)}
+            <li aria-current="page">{title}</li>
+          </ol>
+        </Breadcrumb>
+      )}
+      <Stack direction="horizontal" align="start" justify="between" gap="group" wrap>
+        <Stack gap="related" style={{ flex: '1 1 20rem', minWidth: 0, overflowWrap: 'anywhere' }}>
+          <Typography>
+            <h1 id={headingId}>{title}</h1>
+            {description && <p>{description}</p>}
+          </Typography>
+          {status && <Badge variant="outline" style={{ alignSelf: 'flex-start' }}>{status}</Badge>}
+        </Stack>
+        {actions && <Stack direction="horizontal" align="center" gap="related" wrap role="group" aria-label={actionsLabel}>{actions}</Stack>}
+      </Stack>
+    </Stack>
+  </header>
+)

package/templates/react/project-workspace/src/lumen/project-workspace.tsx

@@ -0,0 +1,112 @@
+import './lumen-template.css'
+
+import {
+  Badge,
+  Button,
+  Card,
+  Progress,
+  Sidebar,
+  Stat,
+  Table,
+  Timeline,
+  TimelineItem
+} from '@santi020k/lumen-react'
+
+export const ProjectWorkspaceTemplate = () => (
+  <div className="lumen-template lumen-template__shell">
+    <Sidebar className="lumen-template__sidebar">
+      <strong>Relay Projects</strong>
+      <nav aria-label="Projects">
+        <a aria-current="page" href="#overview">
+          Overview
+        </a>
+        <a href="#projects">Projects</a>
+        <a href="#activity">Activity</a>
+      </nav>
+    </Sidebar>
+    <main className="lumen-template__main" id="overview">
+      <header className="lumen-template__header">
+        <div>
+          <Badge variant="outline">Team delivery</Badge>
+          <h1>Team workspace</h1>
+          <p>Priorities, delivery health, and next decisions.</p>
+        </div>
+        <Button>New project</Button>
+      </header>
+      <section
+        className="lumen-template__metrics"
+        aria-label="Delivery metrics"
+      >
+        <Card className="lumen-template__metric">
+          <Stat label="Open tasks" value="42" />
+          <Badge variant="warning">6 due soon</Badge>
+        </Card>
+        <Card className="lumen-template__metric">
+          <Stat label="Milestones reached" value="18" />
+          <Badge variant="success">+4</Badge>
+        </Card>
+        <Card className="lumen-template__metric">
+          <Stat label="At-risk projects" value="2" />
+          <Badge variant="destructive">Needs help</Badge>
+        </Card>
+        <Card className="lumen-template__metric">
+          <Stat label="Delivery velocity" value="46 pts" />
+          <Badge variant="success">+6.4%</Badge>
+        </Card>
+      </section>
+      <section className="lumen-template__grid">
+        <Card className="lumen-template__panel">
+          <h2>Active workstreams</h2>
+          <p>Mobile checkout · 72%</p>
+          <Progress aria-label="Mobile checkout is 72% complete" value={72} />
+          <p>Billing migration · 54%</p>
+          <Progress aria-label="Billing migration is 54% complete" value={54} />
+        </Card>
+        <Card className="lumen-template__panel" id="activity">
+          <h2>Recent activity</h2>
+          <Timeline>
+            <TimelineItem>Amina completed checkout validation</TimelineItem>
+            <TimelineItem>Jon reviewed billing retries</TimelineItem>
+            <TimelineItem>Nora moved tokens to review</TimelineItem>
+          </Timeline>
+        </Card>
+      </section>
+      <Card className="lumen-template__panel" id="projects">
+        <div className="lumen-template__section-header">
+          <h2>Priority projects</h2>
+          <Button variant="ghost">View all</Button>
+        </div>
+        <Table className="lumen-template__table">
+          <table>
+            <thead>
+              <tr>
+                <th>Project</th>
+                <th>Owner</th>
+                <th>Status</th>
+                <th>Progress</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Mobile checkout</td>
+                <td>Amina</td>
+                <td>
+                  <Badge variant="success">Active</Badge>
+                </td>
+                <td>72%</td>
+              </tr>
+              <tr>
+                <td>Billing migration</td>
+                <td>Jon</td>
+                <td>
+                  <Badge variant="destructive">At risk</Badge>
+                </td>
+                <td>54%</td>
+              </tr>
+            </tbody>
+          </table>
+        </Table>
+      </Card>
+    </main>
+  </div>
+)

package/templates/react/record-workspace/src/lumen/record-workspace.tsx

@@ -0,0 +1,67 @@
+import type { ReactNode } from 'react'
+
+import { Badge, Card, Descriptions, type DescriptionsProps, FormattedDate, Grid, Stack, Timeline, TimelineItem } from '@santi020k/lumen-react'
+
+export interface RecordWorkspaceEvent {
+  id: string
+  dateTime: string
+  dateLabel: string
+  title: string
+  description: ReactNode
+  stateLabel?: string
+  /** Authored link or action connecting a correction to its original event. */
+  related?: ReactNode
+}
+
+export interface RecordWorkspaceRecipeProps {
+  title: string
+  headingId: string
+  status: ReactNode
+  actions?: ReactNode
+  facts: NonNullable<DescriptionsProps['items']>
+  children?: ReactNode
+  events: readonly RecordWorkspaceEvent[]
+  historyLabel: string
+  emptyHistoryLabel: string
+  /** Supply ErrorState for failures or loading feedback instead of claiming empty history. */
+  historyFeedback?: ReactNode
+}
+
+/** Generic record composition. Balances, event order and correction semantics remain host-owned. */
+export const RecordWorkspaceRecipe = ({
+  title, headingId, status, actions, facts, children, events, historyLabel, emptyHistoryLabel, historyFeedback
+}: RecordWorkspaceRecipeProps) => (
+  <section aria-labelledby={headingId}>
+    <Stack gap="group">
+      <Stack direction="horizontal" wrap gap="related">
+        <h2 id={headingId}>{title}</h2>
+        {status}
+        {actions}
+      </Stack>
+      <Grid minItemWidth="18rem" gap="group">
+        <Card>
+          <Descriptions items={facts} />
+          {children}
+        </Card>
+        <Card>
+          <h3>{historyLabel}</h3>
+          {historyFeedback ?? (events.length === 0 ?
+            <p>{emptyHistoryLabel}</p> :
+            (
+              <Timeline aria-label={historyLabel}>
+                {events.map(event => (
+                  <TimelineItem key={event.id}>
+                    <FormattedDate dateTime={event.dateTime}>{event.dateLabel}</FormattedDate>
+                    <h4>{event.title}</h4>
+                    {event.stateLabel && <Badge variant="outline">{event.stateLabel}</Badge>}
+                    <div>{event.description}</div>
+                    {event.related}
+                  </TimelineItem>
+                ))}
+              </Timeline>
+            ))}
+        </Card>
+      </Grid>
+    </Stack>
+  </section>
+)

package/templates/react/review-workflow/src/lumen/review-workflow.tsx

@@ -0,0 +1,202 @@
+import type { ReactNode } from 'react'
+import { useLayoutEffect, useRef, useState } from 'react'
+
+import { type LumenChangeSummaryItem } from '@santi020k/lumen-core'
+import { Alert, Button, ChangeSummary, ErrorSummary, Form, type LumenFormIssue, type LumenFormWorkflowOptions, type LumenReviewResult, Stack, useLumenFormWorkflow, useLumenReviewWorkflow } from '@santi020k/lumen-react'
+
+export interface ReviewProposal<T> {
+  value: T
+  changes: readonly LumenChangeSummaryItem[]
+}
+
+export interface ReviewWorkflowRecipeProps<T> {
+  label: string
+  /** Also changes when an external/programmatic draft or server revision changes. */
+  revision: string
+  children: (state: { pending: boolean, errors: readonly LumenFormIssue[] }) => ReactNode
+  prepare: (values: FormData) => ReviewProposal<T> | undefined
+  submit: (proposal: T) => Promise<LumenReviewResult>
+  /** Check the command outcome at the server; never submit again from this callback. */
+  reconcile?: () => Promise<{ status: 'success' } | { status: 'failure', message: string }>
+  validation?: LumenFormWorkflowOptions
+  labels: {
+    errors: string
+    review: string
+    confirm: string
+    edit: string
+    success: string
+    uncertain: string
+    checkResult: string
+    before: string
+    after: string
+    changed: string
+    unchanged: string
+  }
+}
+
+type ReviewController<T> = ReturnType<typeof useLumenReviewWorkflow<ReviewProposal<T>>>
+
+const ResultCheck = ({ reconcile, onResult, label }: {
+  reconcile: NonNullable<ReviewWorkflowRecipeProps<unknown>['reconcile']>
+  onResult: (result: Awaited<ReturnType<NonNullable<ReviewWorkflowRecipeProps<unknown>['reconcile']>>>) => void
+  label: string
+}) => {
+  const [checking, setChecking] = useState(false)
+  const checkingRef = useRef(false)
+
+  const check = async () => {
+    if (checkingRef.current) return
+
+    checkingRef.current = true
+
+    setChecking(true)
+
+    try {
+      onResult(await reconcile())
+    } catch {
+      // Keep the visible unknown-outcome guidance and permit another status check.
+    } finally {
+      checkingRef.current = false
+
+      setChecking(false)
+    }
+  }
+
+  return (
+    <Button
+      type="button"
+      loading={checking}
+      disabled={checking}
+      onClick={() => {
+        void check()
+      }}
+    >
+      {label}
+    </Button>
+  )
+}
+
+const ReviewActions = <T,>({ workflow, labels, reconcile, edit }: {
+  workflow: ReviewController<T>
+  labels: ReviewWorkflowRecipeProps<T>['labels']
+  reconcile: ReviewWorkflowRecipeProps<T>['reconcile']
+  edit: () => void
+}) => {
+  if (workflow.status === 'editing') return <Button type="submit">{labels.review}</Button>
+
+  if (workflow.status === 'success') return null
+
+  if (workflow.status === 'uncertain') return reconcile ?
+    <ResultCheck reconcile={reconcile} onResult={workflow.reconcile} label={labels.checkResult} /> :
+    null
+
+  return (
+    <Stack direction="horizontal" wrap gap="related">
+      <Button
+        type="button"
+        loading={workflow.status === 'pending'}
+        disabled={workflow.status === 'pending'}
+        onClick={() => {
+          void workflow.confirm()
+        }}
+      >
+        {labels.confirm}
+      </Button>
+      <Button type="button" variant="outline" disabled={workflow.status === 'pending'} onClick={edit}>{labels.edit}</Button>
+    </Stack>
+  )
+}
+
+/** Supply an explicit allowlist in prepare; never include credentials or uploaded documents in changes. */
+export const ReviewWorkflowRecipe = <T,>({
+  label, revision, children, prepare, submit, reconcile, validation, labels
+}: ReviewWorkflowRecipeProps<T>) => {
+  const form = useLumenFormWorkflow(validation)
+  const [editRevision, setEditRevision] = useState(0)
+  const reviewRef = useRef<HTMLElement>(null)
+  const feedbackRef = useRef<HTMLDivElement>(null)
+
+  const workflow = useLumenReviewWorkflow<ReviewProposal<T>>({
+    revision: `${revision}:${editRevision}`,
+    submit: proposal => submit(proposal.value),
+    uncertainMessage: labels.uncertain
+  })
+
+  const pending = workflow.status === 'pending' || workflow.status === 'uncertain'
+  const review = workflow.proposal
+
+  useLayoutEffect(() => {
+    if (workflow.status === 'review') reviewRef.current?.focus()
+    else if (['failure', 'uncertain', 'success'].includes(workflow.status)) feedbackRef.current?.focus()
+  }, [workflow.status])
+
+  const invalidate = () => {
+    if (workflow.edit()) setEditRevision(current => current + 1)
+  }
+
+  return (
+    <Form
+      {...form.formProps}
+      aria-label={label}
+      aria-busy={workflow.status === 'pending'}
+      onInput={event => {
+        form.formProps.onInput(event)
+
+        invalidate()
+      }}
+      onChange={event => {
+        form.formProps.onChange(event)
+
+        invalidate()
+      }}
+      onReset={event => {
+        if (pending) event.preventDefault()
+        else invalidate()
+
+        form.formProps.onReset(event)
+      }}
+      onSubmit={event => {
+        event.preventDefault()
+
+        if (pending || !form.validate(event.currentTarget)) return
+
+        const proposal = prepare(new FormData(event.currentTarget))
+
+        if (proposal) workflow.review(proposal)
+      }}
+    >
+      <ErrorSummary heading={labels.errors} errors={{ fields: [...form.errors], form: [] }} />
+      <fieldset disabled={pending} style={{ border: 0, margin: 0, padding: 0, minWidth: 0 }}>
+        <legend className="sr-only">{label}</legend>
+        {children({ pending, errors: form.errors })}
+      </fieldset>
+      {review && workflow.status !== 'success' && (
+        <ChangeSummary
+          ref={reviewRef}
+          tabIndex={-1}
+          label={labels.review}
+          items={review.changes}
+          beforeLabel={labels.before}
+          afterLabel={labels.after}
+          changedLabel={labels.changed}
+          unchangedLabel={labels.unchanged}
+        />
+      )}
+      <div ref={feedbackRef} tabIndex={-1}>
+        {(workflow.status === 'failure' || workflow.status === 'uncertain') &&
+          <Alert role="alert" variant="warning">{workflow.message}</Alert>}
+        {workflow.status === 'success' && <Alert role="status" variant="success">{labels.success}</Alert>}
+      </div>
+      <ReviewActions
+        workflow={workflow}
+        labels={labels}
+        reconcile={reconcile}
+        edit={() => {
+          invalidate()
+
+          form.formRef.current?.querySelector<HTMLElement>('input:not([type="hidden"]), select, textarea')?.focus()
+        }}
+      />
+    </Form>
+  )
+}

package/templates/react/rich-text-editor/src/lumen/rich-text-editor.tsx

@@ -0,0 +1,33 @@
+import {
+  Button,
+  ButtonGroup,
+  RichTextEditor,
+  Textarea,
+  ToggleGroup,
+  useRichTextEditor
+} from '@santi020k/lumen-react'
+
+export const RichTextEditorRecipe = () => {
+  const editor = useRichTextEditor()
+
+  return (
+    <RichTextEditor className="lumen-recipe lumen-recipe--rich-text-editor">
+      <div role="toolbar" aria-label="Editor toolbar">
+        <ButtonGroup>
+          <Button {...editor.getCommandProps('bold')}>Bold</Button>
+          <Button {...editor.getCommandProps('italic')}>Italic</Button>
+        </ButtonGroup>
+        <ToggleGroup>
+          <button
+            {...editor.getCommandProps('insertUnorderedList')}
+            type="button"
+          >
+            List
+          </button>
+        </ToggleGroup>
+      </div>
+      <div {...editor.getEditableProps()}>Draft release notes...</div>
+      <Textarea name="fallback" placeholder="Plain text fallback" />
+    </RichTextEditor>
+  )
+}

package/templates/react/saas-admin/src/lumen/saas-admin.tsx

@@ -0,0 +1,119 @@
+import './lumen-template.css'
+
+import {
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Progress,
+  SearchField,
+  Sidebar,
+  Stat,
+  Table
+} from '@santi020k/lumen-react'
+
+export const SaasAdminTemplate = () => (
+  <div className="lumen-template lumen-template__shell">
+    <Sidebar className="lumen-template__sidebar">
+      <strong>Orbit Admin</strong>
+      <nav aria-label="Administration">
+        <a aria-current="page" href="#overview">
+          Overview
+        </a>
+        <a href="#members">Members</a>
+        <a href="#billing">Billing</a>
+      </nav>
+    </Sidebar>
+    <main className="lumen-template__main" id="overview">
+      <header className="lumen-template__header">
+        <div>
+          <Badge variant="outline">Workspace administration</Badge>
+          <h1>Good morning, Maya</h1>
+          <p>Access, billing, and operational health.</p>
+        </div>
+        <Button>Invite members</Button>
+      </header>
+      <Alert>
+        <strong>Quarterly access review is ready.</strong>
+        {' '}
+        Confirm eight
+        elevated roles before July 12.
+      </Alert>
+      <section
+        className="lumen-template__metrics"
+        aria-label="Workspace metrics"
+      >
+        <Card className="lumen-template__metric">
+          <Stat label="Workspace members" value="248" />
+          <Badge variant="success">+24</Badge>
+        </Card>
+        <Card className="lumen-template__metric">
+          <Stat label="Seat activation" value="91%" />
+          <Badge variant="success">Healthy</Badge>
+        </Card>
+        <Card className="lumen-template__metric">
+          <Stat label="Access reviews" value="8" />
+          <Badge variant="warning">3 pending</Badge>
+        </Card>
+        <Card className="lumen-template__metric">
+          <Stat label="Availability" value="99.99%" />
+          <Badge variant="success">Normal</Badge>
+        </Card>
+      </section>
+      <section className="lumen-template__grid" id="billing">
+        <Card className="lumen-template__panel">
+          <h2>Plan utilization</h2>
+          <Stat label="Seats used" value="248 / 300" />
+          <Progress aria-label="248 of 300 seats used" max={300} value={248} />
+        </Card>
+        <Card className="lumen-template__panel">
+          <h2>Security posture</h2>
+          <ul className="lumen-template__list">
+            <li>Single sign-on enforced</li>
+            <li>Domain verification complete</li>
+            <li>3 recovery codes need rotation</li>
+          </ul>
+        </Card>
+      </section>
+      <Card className="lumen-template__panel" id="members">
+        <div className="lumen-template__section-header">
+          <h2>Recently active members</h2>
+          <SearchField
+            aria-label="Search members"
+            placeholder="Search members"
+          />
+        </div>
+        <Table className="lumen-template__table">
+          <table>
+            <thead>
+              <tr>
+                <th>Member</th>
+                <th>Team</th>
+                <th>Status</th>
+                <th>Role</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Amina Bello</td>
+                <td>Design</td>
+                <td>
+                  <Badge variant="success">Active</Badge>
+                </td>
+                <td>Admin</td>
+              </tr>
+              <tr>
+                <td>Theo Martin</td>
+                <td>Success</td>
+                <td>
+                  <Badge variant="warning">Pending</Badge>
+                </td>
+                <td>Member</td>
+              </tr>
+            </tbody>
+          </table>
+        </Table>
+      </Card>
+    </main>
+  </div>
+)