@santi020k/lumen 3.0.1 → 4.1.0

package/templates/react/content-flow-settings/src/lumen/content-flow-settings.tsx

@@ -0,0 +1,26 @@
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Field, Input, Label, Stack } from '@santi020k/lumen-react'
+
+export const ContentFlowSettingsRecipe = () => (
+  <Card as="section" aria-labelledby="notification-heading">
+    <CardHeader>
+      <CardTitle as="h2" id="notification-heading">Notifications</CardTitle>
+      <CardDescription>Choose where your team receives updates.</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <Stack gap="group">
+        <Field>
+          <Label htmlFor="team-name">Team name</Label>
+          <Input id="team-name" name="team" autoComplete="organization" />
+        </Field>
+        <Field>
+          <Label htmlFor="team-email">Team email</Label>
+          <Input id="team-email" name="email" type="email" autoComplete="email" />
+        </Field>
+      </Stack>
+    </CardContent>
+    <CardFooter>
+      <Button>Save preferences</Button>
+      <Button variant="secondary">Discard changes</Button>
+    </CardFooter>
+  </Card>
+)

package/templates/react/data-collections/src/lumen/data-collections.tsx

@@ -0,0 +1,60 @@
+import type { CSSProperties } from 'react'
+
+import {
+  Command,
+  DataTable,
+  Pagination,
+  Tree,
+  TreeGrid,
+  VirtualList
+} from '@santi020k/lumen-react'
+
+const virtualListStyle = { '--ui-list-height': '12rem' } as CSSProperties
+
+export const DataCollectionsRecipe = () => (
+  <section className="lumen-recipe lumen-recipe--data-collections">
+    <Command>
+      <input type="search" placeholder="Filter records" />
+      <button data-ui-command-item type="button">
+        Open docs
+      </button>
+    </Command>
+    <DataTable>
+      <table>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Status</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>Docs</td>
+            <td>Ready</td>
+          </tr>
+        </tbody>
+      </table>
+    </DataTable>
+    <Tree aria-label="Files">
+      <div role="treeitem" aria-expanded="true">
+        src
+      </div>
+      <div role="treeitem">index.ts</div>
+    </Tree>
+    <TreeGrid aria-label="Project status">
+      <div role="row">
+        <span role="gridcell">Docs</span>
+        <span role="gridcell">Ready</span>
+      </div>
+    </TreeGrid>
+    <VirtualList data-ui-item-size="44" style={virtualListStyle}>
+      <div>Row 1</div>
+      <div>Row 2</div>
+      <div>Row 3</div>
+    </VirtualList>
+    <Pagination>
+      <a href="?page=1">Previous</a>
+      <a href="?page=2">Next</a>
+    </Pagination>
+  </section>
+)

package/templates/react/feature-preview/src/lumen/feature-preview.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import { useState } from 'react'
+
+import { Button, Card, MotionGroup, Stack, Typography, VisualEffect } from '@santi020k/lumen-react'
+
+const features = ['Plan', 'Review', 'Ship'] as const
+const descriptions = { Plan: 'Bring the next three tasks into focus.', Review: 'Compare a proposal before deciding.', Ship: 'Check the release evidence before publishing.' }
+
+export const FeaturePreviewRecipe = () => {
+  const [feature, setFeature] = useState<typeof features[number]>('Plan')
+
+  return (
+    <Stack gap="group">
+      <Typography><h2>From idea to delivery</h2></Typography>
+      <Stack direction="horizontal" gap="related" role="group" aria-label="Preview a workflow stage">
+        {features.map(item => (
+          <Button
+            key={item}
+            aria-pressed={feature === item}
+            onClick={() => {
+              setFeature(item)
+            }}
+          >
+            {item}
+          </Button>
+        ))}
+      </Stack>
+      <MotionGroup>
+        <Card key={feature} data-ui-motion-key={feature}>
+          <VisualEffect variant="mesh">
+            <Typography>
+              <h3>{feature}</h3>
+              <p>{descriptions[feature]}</p>
+            </Typography>
+          </VisualEffect>
+        </Card>
+      </MotionGroup>
+      <span role="status">{`Previewing ${feature.toLowerCase()}.`}</span>
+    </Stack>
+  )
+}

package/templates/react/guided-onboarding/src/lumen/guided-onboarding.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+import { useEffect, useId, useRef, useState } from 'react'
+
+import { Button, Card, Form, Input, Label, Stack, Stepper, Typography } from '@santi020k/lumen-react'
+
+export const GuidedOnboardingRecipe = ({ onComplete }: { onComplete?: (workspace: string) => void }) => {
+  const id = useId()
+  const [step, setStep] = useState(0)
+  const [workspace, setWorkspace] = useState('')
+  const stepHeadingRef = useRef<HTMLHeadingElement>(null)
+  const mountedRef = useRef(false)
+
+  useEffect(() => {
+    if (mountedRef.current) stepHeadingRef.current?.focus()
+
+    mountedRef.current = true
+  }, [step])
+
+  const steps = [{ title: 'Workspace' }, { title: 'Review' }, { title: 'Ready' }]
+
+  return (
+    <Card>
+      <Stack gap="group">
+        <Typography>
+          <h2>Prepare your workspace</h2>
+          <p>This draft stays local until your application handles completion.</p>
+        </Typography>
+        <Stepper steps={steps} currentStep={step} />
+        <Form
+          enhance={false}
+          onSubmit={event => {
+            event.preventDefault()
+
+            if (step === 0) setStep(1); else {
+              onComplete?.(workspace.trim())
+
+              setStep(2)
+            }
+          }}
+        >
+          <Stack gap="group">
+            {step === 0 && (
+              <Stack gap="related">
+                <h3 ref={stepHeadingRef} tabIndex={-1}>Workspace</h3>
+                <Label htmlFor={id}>Workspace name</Label>
+                <Input
+                  id={id}
+                  required
+                  maxLength={80}
+                  value={workspace}
+                  onChange={event => {
+                    setWorkspace(event.currentTarget.value)
+                  }}
+                />
+              </Stack>
+            )}
+            {step === 1 && (
+              <Typography>
+                <h3 ref={stepHeadingRef} tabIndex={-1}>Review your draft</h3>
+                <p>{`Workspace: ${workspace}`}</p>
+              </Typography>
+            )}
+            {step === 2 && (
+              <Typography>
+                <h3 ref={stepHeadingRef} tabIndex={-1}>Ready</h3>
+                <p role="status">Workspace draft completed.</p>
+              </Typography>
+            )}
+            <Stack direction="horizontal" gap="related">
+              {step === 1 && (
+                <Button
+                  type="button"
+                  variant="secondary"
+                  onClick={() => {
+                    setStep(0)
+                  }}
+                >
+                  Back
+                </Button>
+              )}
+              {step < 2 && <Button type="submit" disabled={!workspace.trim()}>{step === 0 ? 'Continue' : 'Complete setup'}</Button>}
+              {step === 2 && (
+                <Button
+                  type="button"
+                  variant="secondary"
+                  onClick={() => {
+                    setStep(0)
+                  }}
+                >
+                  Edit draft
+                </Button>
+              )}
+            </Stack>
+          </Stack>
+        </Form>
+      </Stack>
+    </Card>
+  )
+}

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

@@ -0,0 +1,150 @@
+import type { ReactNode } from 'react'
+import { useId, useRef, useState } from 'react'
+
+import { Alert, Badge, Button, Card, ChangeSummary, type ChangeSummaryProps, Stack } from '@santi020k/lumen-react'
+
+export interface ImportReviewIssue {
+  id: string
+  location: string
+  message: string
+  blocking: boolean
+}
+
+export interface ImportReviewRecord {
+  id: string
+  label: string
+  changes: NonNullable<ChangeSummaryProps['items']>
+}
+
+export interface ImportReviewRecipeProps {
+  label: string
+  issues: readonly ImportReviewIssue[]
+  records: readonly ImportReviewRecord[]
+  /** Already localized counts and destination supplied by the host. */
+  summary: ReactNode
+  pending?: boolean
+  onConfirm: () => void
+  /** Application controls parsing, versioned proposals, confirmation and idempotency. */
+  onIssue?: (id: string) => void
+  labels: {
+    issues: string
+    records: string
+    blocking: string
+    warning: string
+    empty: string
+    previous: string
+    next: string
+    confirm: string
+    before: string
+    after: string
+    changed: string
+    unchanged: string
+    position: (page: number, count: number) => string
+  }
+}
+
+/** Pure review presentation. No CSV parsing, record matching or implicit reconciliation. */
+export const ImportReviewRecipe = ({
+  label, issues, records, summary, pending = false, onConfirm, onIssue, labels
+}: ImportReviewRecipeProps) => {
+  const [selectedId, setSelectedId] = useState<string | undefined>(undefined)
+  const index = Math.max(0, records.findIndex(record => record.id === selectedId))
+  const record = records[index]
+  const headingId = useId()
+  const detailRef = useRef<HTMLElement>(null)
+
+  const move = (next: number) => {
+    const target = records[next]
+
+    if (!target) return
+
+    setSelectedId(target.id)
+
+    detailRef.current?.focus()
+  }
+
+  return (
+    <section aria-label={label} aria-busy={pending}>
+      <Stack gap="group">
+        {summary}
+        {issues.length > 0 && (
+          <Alert variant={issues.some(issue => issue.blocking) ? 'warning' : 'default'}>
+            <h3>{labels.issues}</h3>
+            <ul>
+              {issues.map(issue => (
+                <li key={issue.id}>
+                  <Badge variant={issue.blocking ? 'warning' : 'outline'}>{issue.blocking ? labels.blocking : labels.warning}</Badge>
+                  {' '}
+                  {onIssue ?
+                    (
+                      <Button
+                        type="button"
+                        variant="link"
+                        disabled={pending}
+                        onClick={() => {
+                          onIssue(issue.id)
+                        }}
+                      >
+                        {issue.location}
+                      </Button>
+                    ) :
+                    <strong>{issue.location}</strong>}
+                  {' '}
+                  {issue.message}
+                </li>
+              ))}
+            </ul>
+          </Alert>
+        )}
+        {record ?
+          (
+            <Card>
+              <section ref={detailRef} tabIndex={-1} aria-labelledby={headingId}>
+                <h3 id={headingId}>{record.label}</h3>
+                <ChangeSummary
+                  label={labels.records}
+                  items={record.changes}
+                  beforeLabel={labels.before}
+                  afterLabel={labels.after}
+                  changedLabel={labels.changed}
+                  unchangedLabel={labels.unchanged}
+                />
+              </section>
+              <Stack direction="horizontal" wrap gap="related">
+                <Button
+                  type="button"
+                  variant="outline"
+                  disabled={pending || index === 0}
+                  onClick={() => {
+                    move(index - 1)
+                  }}
+                >
+                  {labels.previous}
+                </Button>
+                <p role="status">{labels.position(index + 1, records.length)}</p>
+                <Button
+                  type="button"
+                  variant="outline"
+                  disabled={pending || index >= records.length - 1}
+                  onClick={() => {
+                    move(index + 1)
+                  }}
+                >
+                  {labels.next}
+                </Button>
+              </Stack>
+            </Card>
+          ) :
+          <p role="status">{labels.empty}</p>}
+        <Button
+          type="button"
+          loading={pending}
+          disabled={pending || records.length === 0 || issues.some(issue => issue.blocking)}
+          onClick={onConfirm}
+        >
+          {labels.confirm}
+        </Button>
+      </Stack>
+    </section>
+  )
+}

package/templates/react/interactive-pricing/src/lumen/interactive-pricing.tsx

@@ -0,0 +1,60 @@
+'use client'
+
+import { useState } from 'react'
+
+import { Button, Card, Grid, Stack, Typography, VisualEffect } from '@santi020k/lumen-react'
+
+export interface PlanSelection { billing: 'monthly' | 'annual', plan: 'starter' | 'team' }
+export const InteractivePricingRecipe = ({ onSelect }: { onSelect?: (selection: PlanSelection) => void }) => {
+  const [billing, setBilling] = useState<PlanSelection['billing']>('monthly')
+  const [selected, setSelected] = useState('')
+  const prices = { starter: { monthly: 10, annual: 96 }, team: { monthly: 24, annual: 240 } }
+
+  return (
+    <Stack gap="group" aria-label="Example pricing">
+      <Typography>
+        <h2>A plan for your next project</h2>
+        <p>Illustrative prices. Connect selections to your own checkout.</p>
+      </Typography>
+      <Stack direction="horizontal" gap="related" role="group" aria-label="Billing period">
+        <Button
+          aria-pressed={billing === 'monthly'}
+          onClick={() => {
+            setBilling('monthly')
+          }}
+        >
+          Monthly
+        </Button>
+        <Button
+          aria-pressed={billing === 'annual'}
+          onClick={() => {
+            setBilling('annual')
+          }}
+        >
+          Annual
+        </Button>
+      </Stack>
+      <Grid columns="auto">
+        {(['starter', 'team'] as const).map(plan => (
+          <Card key={plan}>
+            <VisualEffect variant={plan === 'team' ? 'mesh' : 'border'}>
+              <Typography>
+                <h3>{plan === 'starter' ? 'Starter' : 'Team'}</h3>
+                <p>{`$${prices[plan][billing]} / ${billing === 'annual' ? 'year' : 'month'}`}</p>
+              </Typography>
+              <Button onClick={() => {
+                setSelected(`${plan}, ${billing}`)
+
+                onSelect?.({ plan, billing })
+              }}
+              >
+                {`Choose ${plan}`}
+              </Button>
+            </VisualEffect>
+          </Card>
+        ))}
+      </Grid>
+      <span role="status">{selected ? `Selected ${selected}.` : 'Select a plan to compare billing.'}</span>
+    </Stack>
+  )
+}

package/templates/react/media-workspace/src/lumen/adjustment-controls.tsx

@@ -0,0 +1,61 @@
+'use client'
+
+import { useId } from 'react'
+
+import { Badge, Button, Field, Label, Slider, Stack } from '@santi020k/lumen-react'
+
+export interface AdjustmentControlProps {
+  defaultValue: number
+  disabled?: boolean
+  formatValue: (value: number) => string
+  label: string
+  max: number
+  min: number
+  modifiedLabel: string
+  onValueChange: (value: number) => void
+  resetLabel: string
+  step: number
+  value: number
+}
+
+/** Draft adjustment state belongs to the host; a reset requests the declared neutral value. */
+export const AdjustmentControlRecipe = ({
+  defaultValue, disabled, formatValue, label, max, min, modifiedLabel, onValueChange, resetLabel,
+  step, value
+}: AdjustmentControlProps) => {
+  const id = useId()
+  const outputId = useId()
+  const modified = value !== defaultValue
+
+  return (
+    <Field>
+      <Stack direction="horizontal" align="center" justify="between" wrap>
+        <Label htmlFor={id}>{label}</Label>
+        <output id={outputId} htmlFor={id}>{formatValue(value)}</output>
+        {modified && <Badge variant="secondary">{modifiedLabel}</Badge>}
+      </Stack>
+      <Slider
+        id={id}
+        aria-describedby={outputId}
+        aria-valuetext={formatValue(value)}
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        disabled={disabled}
+        onChange={event => {
+          onValueChange(event.currentTarget.valueAsNumber)
+        }}
+      />
+      <Button
+        variant="ghost"
+        disabled={disabled === true || !modified}
+        onClick={() => {
+          onValueChange(defaultValue)
+        }}
+      >
+        {resetLabel}
+      </Button>
+    </Field>
+  )
+}

package/templates/react/media-workspace/src/lumen/media-processing.tsx

@@ -0,0 +1,43 @@
+'use client'
+
+import { Button, ErrorState, Progress, Stack } from '@santi020k/lumen-react'
+
+export type MediaProcessingState =
+  | { phase: 'idle' | 'cancelled' | 'success', message: string } |
+  { phase: 'pending', message: string, progress: number | null } |
+  { phase: 'error', message: string, recovery: string }
+
+export interface MediaProcessingRecipeProps {
+  cancelLabel: string
+  onCancel: () => void
+  onRetry: () => void
+  onStart: () => void
+  progressLabel: string
+  retryLabel: string
+  startLabel: string
+  state: MediaProcessingState
+}
+
+/** Host-owned jobs control all transitions; cancellation is complete only after acknowledgement. */
+export const MediaProcessingRecipe = ({
+  cancelLabel, onCancel, onRetry, onStart, progressLabel, retryLabel, startLabel, state
+}: MediaProcessingRecipeProps) => (
+  <Stack gap="related">
+    {state.phase === 'error' ?
+      (
+        <ErrorState title={state.message} description={state.recovery} graphic={false} announce="polite" headingLevel={3}>
+          <Button onClick={onRetry}>{retryLabel}</Button>
+        </ErrorState>
+      ) :
+      <p role="status">{state.message}</p>}
+    {state.phase === 'pending' && (
+      <>
+        {state.progress !== null && Number.isFinite(state.progress) && (
+          <Progress aria-label={progressLabel} value={Math.min(100, Math.max(0, state.progress))} />
+        )}
+        <Button variant="outline" onClick={onCancel}>{cancelLabel}</Button>
+      </>
+    )}
+    {state.phase !== 'pending' && state.phase !== 'error' && <Button onClick={onStart}>{startLabel}</Button>}
+  </Stack>
+)

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

@@ -0,0 +1,100 @@
+'use client'
+
+import type { ReactNode } from 'react'
+
+import { moveLumenMediaItem, resolveLumenMediaSelection, toggleLumenMediaSelection } from '@santi020k/lumen-core/media-workspace'
+import { Button, Card, Image, MediaFilmstrip, MediaThumbnail, Stack, Toolbar } from '@santi020k/lumen-react'
+
+// Import the installed media-workspace.css once at the application's style boundary.
+
+export interface MediaWorkspaceItem {
+  alt: string
+  disabled?: boolean
+  height: number
+  id: string
+  label: string
+  src: string
+  width: number
+}
+
+export interface MediaWorkspaceRecipeProps {
+  bottomControls?: ReactNode
+  collectionLabel: string
+  formatSelection: (count: number) => string
+  inspector: ReactNode
+  inspectorLabel: string
+  items: readonly MediaWorkspaceItem[]
+  moveEarlierLabel: string
+  moveLaterLabel: string
+  onItemsChange: (items: MediaWorkspaceItem[]) => void
+  onSelectionChange: (ids: string[]) => void
+  preview: ReactNode
+  previewLabel: string
+  selectedIds: readonly string[]
+  showTitle?: boolean
+  title: string
+  tools: ReactNode
+  toolsLabel: string
+}
+
+/** Compose a preview, supporting controls and inspector without owning photo services or drafts. */
+export const MediaWorkspaceRecipe = ({
+  bottomControls, collectionLabel, formatSelection, inspector, inspectorLabel, items,
+  moveEarlierLabel, moveLaterLabel, onItemsChange, onSelectionChange, preview, previewLabel,
+  selectedIds, showTitle = true, title, tools, toolsLabel
+}: MediaWorkspaceRecipeProps) => {
+  const selection = resolveLumenMediaSelection(items, selectedIds)
+
+  return (
+    <section className="lumen-media-workspace" aria-label={title}>
+      {showTitle && <h2>{title}</h2>}
+      <div className="lumen-media-workspace__layout">
+        <div className="lumen-media-workspace__preview" role="group" aria-label={previewLabel}>{preview}</div>
+        <Card className="lumen-media-workspace__inspector" aria-label={inspectorLabel}>{inspector}</Card>
+      </div>
+      <Card glass="subtle" className="lumen-media-workspace__tools">
+        <Toolbar aria-label={toolsLabel}>{tools}</Toolbar>
+      </Card>
+      <MediaFilmstrip label={collectionLabel} selectionLabel={formatSelection(selection.length)}>
+        {items.map((item, index) => (
+          <li key={item.id}>
+            <MediaThumbnail
+              label={item.label}
+              order={index + 1}
+              selected={selection.includes(item.id)}
+              disabled={item.disabled}
+              onClick={() => {
+                onSelectionChange(toggleLumenMediaSelection(items, selection, item.id))
+              }}
+            >
+              <Image src={item.src} alt={item.alt} width={item.width} height={item.height} />
+            </MediaThumbnail>
+            <Stack gap="related">
+              <Button
+                variant="outline"
+                aria-label={`${moveEarlierLabel}: ${item.label}`}
+                disabled={item.disabled === true || index === 0}
+                onClick={() => {
+                  onItemsChange(moveLumenMediaItem(items, item.id, index - 1))
+                }}
+              >
+                {moveEarlierLabel}
+              </Button>
+              <Button
+                variant="outline"
+                aria-label={`${moveLaterLabel}: ${item.label}`}
+                disabled={item.disabled === true || index === items.length - 1}
+                onClick={() => {
+                  onItemsChange(moveLumenMediaItem(items, item.id, index + 1))
+                }}
+              >
+                {moveLaterLabel}
+              </Button>
+            </Stack>
+          </li>
+        ))}
+      </MediaFilmstrip>
+      {bottomControls && <Card className="lumen-media-workspace__bottom">{bottomControls}</Card>}
+    </section>
+  )
+}