orbital-ds 0.18.2 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,338 @@
1
+ "use client";
2
+ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
3
+ import { ArrowLeftIcon, ArrowRightIcon, CheckIcon, LoaderCircleIcon } from "lucide-react";
4
+ import * as React from "react";
5
+ import { useDsMessages } from "../hooks/use-ds-messages.js";
6
+ import { dsFormat } from "../lib/i18n.js";
7
+ import { dsWarn } from "../lib/presets.js";
8
+ import { cn } from "../lib/utils.js";
9
+ import {
10
+ AlertDialog,
11
+ AlertDialogAction,
12
+ AlertDialogCancel,
13
+ AlertDialogContent,
14
+ AlertDialogDescription,
15
+ AlertDialogFooter,
16
+ AlertDialogHeader,
17
+ AlertDialogTitle
18
+ } from "./alert-dialog.js";
19
+ import { Button } from "./button.js";
20
+ import {
21
+ Dialog,
22
+ DialogContent,
23
+ DialogDescription,
24
+ DialogHeader,
25
+ DialogTitle
26
+ } from "./dialog.js";
27
+ import { Progress } from "./progress.js";
28
+ import {
29
+ Stepper,
30
+ StepperContent,
31
+ StepperDescription,
32
+ StepperIndicator,
33
+ StepperItem,
34
+ StepperSeparator,
35
+ StepperTitle
36
+ } from "./stepper.js";
37
+ const PRESETS = {
38
+ quick: { presentation: "dialog", progress: "compact", aside: false },
39
+ activation: { presentation: "dialog", progress: "horizontal", aside: true },
40
+ long: { presentation: "page", progress: "vertical", aside: true }
41
+ };
42
+ const REVIEW_ID = "__review";
43
+ function warnCombination(steps, presentation, progress) {
44
+ if (steps >= 6 && presentation === "dialog" && progress === "horizontal")
45
+ dsWarn("StepFlow", `${steps} steps in a dialog with horizontal progress will not fit; use progress="compact" or presentation="page".`);
46
+ if (steps <= 3 && progress === "vertical")
47
+ dsWarn("StepFlow", `${steps} steps do not justify vertical progress; use progress="compact".`);
48
+ if (steps > 8)
49
+ dsWarn("StepFlow", `${steps} steps is too many; group them into sections or split the flow.`);
50
+ }
51
+ function StepFlow({
52
+ steps,
53
+ preset = "activation",
54
+ presentation,
55
+ progress,
56
+ title,
57
+ description,
58
+ aside,
59
+ review,
60
+ result,
61
+ value,
62
+ defaultValue,
63
+ onValueChange,
64
+ onComplete,
65
+ onCancel,
66
+ dirty = false,
67
+ open,
68
+ onOpenChange,
69
+ className
70
+ }) {
71
+ const t = useDsMessages();
72
+ const base = PRESETS[preset];
73
+ const mode = presentation ?? base.presentation;
74
+ const density = progress ?? base.progress;
75
+ const showAside = aside != null && (presentation || progress ? true : base.aside || aside != null);
76
+ const all = React.useMemo(
77
+ () => review != null ? [...steps, { id: REVIEW_ID, title: t.stepFlowReview, content: review }] : steps,
78
+ [steps, review, t.stepFlowReview]
79
+ );
80
+ const [inner, setInner] = React.useState(defaultValue ?? steps[0]?.id);
81
+ const currentId = value ?? inner;
82
+ const index = Math.max(
83
+ 0,
84
+ all.findIndex((s) => s.id === currentId)
85
+ );
86
+ const current = all[index];
87
+ const last = index === all.length - 1;
88
+ const go = React.useCallback(
89
+ (i) => {
90
+ const next = all[Math.min(Math.max(i, 0), all.length - 1)];
91
+ if (!next) return;
92
+ setInner(next.id);
93
+ onValueChange?.(next.id);
94
+ },
95
+ [all, onValueChange]
96
+ );
97
+ React.useEffect(() => {
98
+ warnCombination(steps.length, mode, density);
99
+ }, [steps.length, mode, density]);
100
+ const bodyRef = React.useRef(null);
101
+ const first = React.useRef(true);
102
+ React.useEffect(() => {
103
+ if (first.current) {
104
+ first.current = false;
105
+ return;
106
+ }
107
+ bodyRef.current?.focus({ preventScroll: false });
108
+ }, [index]);
109
+ const [pending, setPending] = React.useState(false);
110
+ const [confirming, setConfirming] = React.useState(false);
111
+ const finish = async () => {
112
+ if (!onComplete) return;
113
+ setPending(true);
114
+ try {
115
+ await onComplete();
116
+ } finally {
117
+ setPending(false);
118
+ }
119
+ };
120
+ const requestClose = () => {
121
+ if (dirty && result == null) setConfirming(true);
122
+ else close();
123
+ };
124
+ const close = () => {
125
+ setConfirming(false);
126
+ onCancel?.();
127
+ onOpenChange?.(false);
128
+ };
129
+ const stepStatus = (i, s) => s.error ? "error" : i < index ? "complete" : i === index ? "current" : "upcoming";
130
+ const rail = density === "vertical";
131
+ const progressNode = /* @__PURE__ */ jsxs("div", { "data-slot": "step-flow-progress", "data-progress": density, className: "min-w-0", children: [
132
+ /* @__PURE__ */ jsxs(
133
+ "div",
134
+ {
135
+ className: cn("flex flex-col gap-2", density !== "compact" && "@[600px]:hidden"),
136
+ children: [
137
+ /* @__PURE__ */ jsxs("div", { className: "flex items-baseline justify-between gap-3 text-xs text-muted-foreground", children: [
138
+ /* @__PURE__ */ jsx("span", { className: "tabular-nums", children: dsFormat(t.stepOf, { n: index + 1, total: all.length }) }),
139
+ /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate text-foreground", children: current?.title })
140
+ ] }),
141
+ /* @__PURE__ */ jsx(
142
+ Progress,
143
+ {
144
+ value: (index + 1) / all.length * 100,
145
+ "aria-label": t.stepFlowProgress
146
+ }
147
+ )
148
+ ]
149
+ }
150
+ ),
151
+ density === "horizontal" && /* @__PURE__ */ jsx(
152
+ Stepper,
153
+ {
154
+ "aria-label": t.stepFlowProgress,
155
+ orientation: "horizontal",
156
+ className: "hidden @[600px]:flex",
157
+ children: all.map((s, i) => /* @__PURE__ */ jsxs(StepperItem, { step: i + 1, status: stepStatus(i, s), children: [
158
+ /* @__PURE__ */ jsx(StepperIndicator, {}),
159
+ /* @__PURE__ */ jsx(StepperContent, { className: "min-w-0 max-w-40", children: /* @__PURE__ */ jsx(StepperTitle, { className: "truncate", children: s.title }) }),
160
+ i < all.length - 1 && /* @__PURE__ */ jsx(StepperSeparator, {})
161
+ ] }, s.id))
162
+ }
163
+ ),
164
+ rail && /* @__PURE__ */ jsx(
165
+ Stepper,
166
+ {
167
+ "aria-label": t.stepFlowProgress,
168
+ orientation: "vertical",
169
+ className: "hidden @[600px]:flex",
170
+ children: all.map((s, i) => /* @__PURE__ */ jsxs(StepperItem, { step: i + 1, status: stepStatus(i, s), children: [
171
+ /* @__PURE__ */ jsx(StepperIndicator, {}),
172
+ /* @__PURE__ */ jsxs(StepperContent, { children: [
173
+ /* @__PURE__ */ jsx(StepperTitle, { children: s.title }),
174
+ s.optional ? /* @__PURE__ */ jsx(StepperDescription, { children: t.stepFlowOptional }) : s.description ? /* @__PURE__ */ jsx(StepperDescription, { children: s.description }) : null
175
+ ] }),
176
+ i < all.length - 1 && /* @__PURE__ */ jsx(StepperSeparator, {})
177
+ ] }, s.id))
178
+ }
179
+ )
180
+ ] });
181
+ const body = result != null ? /* @__PURE__ */ jsx("div", { "data-slot": "step-flow-result", className: "min-w-0", children: result }) : /* @__PURE__ */ jsxs(
182
+ "div",
183
+ {
184
+ ref: bodyRef,
185
+ tabIndex: -1,
186
+ "data-slot": "step-flow-body",
187
+ "data-step": current?.id,
188
+ className: "flex min-w-0 flex-col gap-(--ds-section-gap) outline-none animate-in fade-in-0 slide-in-from-bottom-2 duration-(--ds-motion-base) ease-(--ds-ease-enter) motion-reduce:animate-none",
189
+ children: [
190
+ /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
191
+ /* @__PURE__ */ jsx("h3", { className: "font-display text-base leading-snug font-(--ds-heading-weight)", children: current?.title }),
192
+ current?.optional && /* @__PURE__ */ jsx("span", { className: "text-xs text-muted-foreground", children: t.stepFlowOptional }),
193
+ current?.description && /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: current.description })
194
+ ] }),
195
+ current?.content
196
+ ]
197
+ },
198
+ current?.id
199
+ );
200
+ const footer = result != null ? null : /* @__PURE__ */ jsxs(
201
+ "div",
202
+ {
203
+ "data-slot": "step-flow-footer",
204
+ className: "flex flex-col-reverse gap-2 @[600px]:flex-row @[600px]:items-center @[600px]:justify-end",
205
+ children: [
206
+ /* @__PURE__ */ jsx(
207
+ Button,
208
+ {
209
+ variant: "ghost",
210
+ disabled: pending,
211
+ onClick: requestClose,
212
+ className: "@[600px]:me-auto",
213
+ children: t.stepFlowCancel
214
+ }
215
+ ),
216
+ index > 0 && /* @__PURE__ */ jsxs(Button, { variant: "outline", disabled: pending, onClick: () => go(index - 1), children: [
217
+ /* @__PURE__ */ jsx(ArrowLeftIcon, { "data-icon": "inline-start", className: "rtl:rotate-180" }),
218
+ t.stepFlowBack
219
+ ] }),
220
+ current?.optional && !last && /* @__PURE__ */ jsx(Button, { variant: "ghost", disabled: pending, onClick: () => go(index + 1), children: t.stepFlowSkip }),
221
+ /* @__PURE__ */ jsx(
222
+ Button,
223
+ {
224
+ disabled: pending || current?.invalid,
225
+ "aria-busy": pending || void 0,
226
+ onClick: () => last ? void finish() : go(index + 1),
227
+ children: pending ? /* @__PURE__ */ jsxs(Fragment, { children: [
228
+ /* @__PURE__ */ jsx(LoaderCircleIcon, { "data-icon": "inline-start", className: "animate-spin motion-reduce:animate-none" }),
229
+ t.stepFlowSaving
230
+ ] }) : last ? /* @__PURE__ */ jsxs(Fragment, { children: [
231
+ /* @__PURE__ */ jsx(CheckIcon, { "data-icon": "inline-start" }),
232
+ t.stepFlowFinish
233
+ ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
234
+ t.stepFlowNext,
235
+ /* @__PURE__ */ jsx(ArrowRightIcon, { "data-icon": "inline-end", className: "rtl:rotate-180" })
236
+ ] })
237
+ }
238
+ )
239
+ ]
240
+ }
241
+ );
242
+ const layout = /* @__PURE__ */ jsxs(
243
+ "div",
244
+ {
245
+ "data-slot": "step-flow",
246
+ "data-preset": preset,
247
+ "data-presentation": mode,
248
+ "data-progress": density,
249
+ className: cn(
250
+ "@container flex min-w-0 flex-col gap-(--ds-section-gap)",
251
+ className
252
+ ),
253
+ children: [
254
+ /* @__PURE__ */ jsxs(
255
+ "div",
256
+ {
257
+ className: cn(
258
+ "grid min-w-0 gap-(--ds-section-gap)",
259
+ rail && "@[600px]:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)]"
260
+ ),
261
+ children: [
262
+ result == null && progressNode,
263
+ /* @__PURE__ */ jsxs(
264
+ "div",
265
+ {
266
+ className: cn(
267
+ "grid min-w-0 gap-(--ds-section-gap)",
268
+ showAside && result == null && "@[600px]:grid-cols-[minmax(0,1fr)_minmax(0,0.8fr)]"
269
+ ),
270
+ children: [
271
+ body,
272
+ showAside && result == null && /* @__PURE__ */ jsx("aside", { "data-slot": "step-flow-aside", className: "hidden min-w-0 @[600px]:block", children: aside })
273
+ ]
274
+ }
275
+ )
276
+ ]
277
+ }
278
+ ),
279
+ footer
280
+ ]
281
+ }
282
+ );
283
+ const confirm = /* @__PURE__ */ jsx(AlertDialog, { open: confirming, onOpenChange: setConfirming, children: /* @__PURE__ */ jsxs(AlertDialogContent, { size: "sm", children: [
284
+ /* @__PURE__ */ jsxs(AlertDialogHeader, { children: [
285
+ /* @__PURE__ */ jsx(AlertDialogTitle, { children: t.stepFlowConfirmTitle }),
286
+ /* @__PURE__ */ jsx(AlertDialogDescription, { children: t.stepFlowConfirmBody })
287
+ ] }),
288
+ /* @__PURE__ */ jsxs(AlertDialogFooter, { children: [
289
+ /* @__PURE__ */ jsx(AlertDialogCancel, { children: t.stepFlowConfirmKeep }),
290
+ /* @__PURE__ */ jsx(AlertDialogAction, { variant: "destructive", onClick: close, children: t.stepFlowConfirmDiscard })
291
+ ] })
292
+ ] }) });
293
+ if (mode === "dialog") {
294
+ const wide = rail || showAside;
295
+ return /* @__PURE__ */ jsxs(Fragment, { children: [
296
+ /* @__PURE__ */ jsx(
297
+ Dialog,
298
+ {
299
+ open,
300
+ onOpenChange: (next) => {
301
+ if (next) onOpenChange?.(true);
302
+ else requestClose();
303
+ },
304
+ children: /* @__PURE__ */ jsxs(
305
+ DialogContent,
306
+ {
307
+ className: cn(
308
+ "max-h-[calc(100dvh-2rem)] overflow-y-auto",
309
+ wide ? "sm:max-w-4xl" : "sm:max-w-lg"
310
+ ),
311
+ children: [
312
+ /* @__PURE__ */ jsxs(DialogHeader, { children: [
313
+ /* @__PURE__ */ jsx(DialogTitle, { children: title }),
314
+ description && /* @__PURE__ */ jsx(DialogDescription, { children: description })
315
+ ] }),
316
+ layout
317
+ ]
318
+ }
319
+ )
320
+ }
321
+ ),
322
+ confirm
323
+ ] });
324
+ }
325
+ return /* @__PURE__ */ jsxs(Fragment, { children: [
326
+ /* @__PURE__ */ jsxs("section", { "data-slot": "step-flow-page", className: "flex min-w-0 flex-col gap-(--ds-section-gap)", children: [
327
+ /* @__PURE__ */ jsxs("header", { "data-slot": "step-flow-header", className: "flex flex-col gap-1", children: [
328
+ /* @__PURE__ */ jsx("h2", { className: "font-display text-xl leading-tight font-(--ds-heading-weight)", children: title }),
329
+ description && /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: description })
330
+ ] }),
331
+ layout
332
+ ] }),
333
+ confirm
334
+ ] });
335
+ }
336
+ export {
337
+ StepFlow
338
+ };
package/docs/CONTRACT.md CHANGED
@@ -120,6 +120,40 @@ ya no define, para que una renombrada no se ignore en silencio.
120
120
  `sidebar-primary` y `chart-1`, y comprueba el contraste del texto sobre ellas. Nunca edites
121
121
  el tema dentro de `node_modules` para personalizar una app.
122
122
 
123
+ ## Componentes con presets (patrones de configuración)
124
+
125
+ Un componente de **flujo o maqueta** (StepFlow, FormLayout, EmptyState, StatGroup, ConfirmAction) se configura con un
126
+ `preset`: una intención en inglés que **solo fija valores por defecto**; cualquier prop explícita lo sobrescribe, así sirve
127
+ en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`, `DsPresentation`, `dsWarn`).
128
+
129
+ 1. **Configuración en inglés** (props, valores, tokens, `data-*`); **texto visible o accesible** por `useDsMessages()` en
130
+ los tres catálogos; comentarios y `@note` en español.
131
+ 2. **Nombre del preset = intención** (`quick`, `first-use`, `settings`), nunca el aspecto (`small-modal`).
132
+ 3. **Ejes independientes**: presentación (`dialog | page | inline | sheet`) y densidad (`compact | default | comfortable`)
133
+ son props distintas; los presets las combinan, no las fusionan.
134
+ 4. **El diseño sigue el ancho del contenedor** (container query), no el dispositivo ni la presentación.
135
+ 5. **Aviso en desarrollo** (`dsWarn`, mensaje en inglés) si la combinación no cuadra.
136
+ 6. **Ganchos del DOM**: `data-slot` y `data-preset` (más `data-presentation`/`data-density` si aplica).
137
+ 7. **Un `@note`** que diga cuándo usar cada preset. Catálogo hoy: `StepFlow` (quick · activation · long), `FormLayout`
138
+ (inline · sectioned · settings), `EmptyState` (first-use · no-results · error · forbidden), `StatGroup` (overview ·
139
+ compact · comparison) y `ConfirmAction` (simple · typed).
140
+
141
+ ## Avisos y comunicaciones in-app (qué canal usar)
142
+
143
+ Se elige el canal por **urgencia** y **persistencia**; cada app no lo decide a mano:
144
+
145
+ | Intención | Canal | Persiste | Interrumpe |
146
+ |---|---|---|---|
147
+ | Confirmar una acción de la persona | toast (`Toaster`/`Toast`) | no | no |
148
+ | Aviso de una sección | `Alert` | sí | no |
149
+ | Aviso que afecta a toda la página | `Banner` | hasta resolver | no |
150
+ | Asunto con seguimiento o decisión | campana (`NotificationCenter`) + `NoticeReview` | sí, con estado | solo si es crítico |
151
+ | Bloqueo que exige respuesta ya | `ConfirmAction` / `AlertDialog` | no | sí |
152
+
153
+ Mismo vocabulario en todos: tono `info | success | warning | danger` y estado `new → acknowledged → resolved`.
154
+ `NotificationItem onSelect` abre la revisión; `NoticeReview` tiene presets `read | acknowledge | resolve | respond`
155
+ (modal o `presentation="sheet"`).
156
+
123
157
  ## Reglas de nombres
124
158
 
125
159
  - Todo en **inglés**: tokens, props y valores de variantes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orbital-ds",
3
- "version": "0.18.2",
3
+ "version": "0.21.0",
4
4
  "description": "Sistema de diseño genérico: estructura común + temas con personalidad (qratia, zyro) + ~60 componentes sobre Base UI y Tailwind v4, con contrato verificable y legible por agentes.",
5
5
  "keywords": [
6
6
  "design-system",