@facto-to/design-system 0.1.0-beta.7 → 0.1.0-beta.9

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.
package/AI.md CHANGED
@@ -21,6 +21,8 @@ Public design target: revision v1.2.24. Existing component adoption baseline: ru
21
21
 
22
22
  Quick constraints: React/React DOM 19; styles.css includes tokens; fonts.css registers Inter and must be imported to load it. Legacy HTML is not automatically restyled. SearchField uses native onChange; EnhancedSearchField and Select use onValueChange; Button defaults to type="button"; Toast is composed of provider/root/viewport, not toast.success(). There is no exported data table, chart, date picker or router.
23
23
 
24
+ For optional animation and reduced-motion behavior, read [motion.md](dist/ai/references/motion.md). Motion never owns application requests or completion timing.
25
+
24
26
  ## Optional skill installation
25
27
 
26
28
  From the frontend repository where this package is installed:
package/README.md CHANGED
@@ -196,3 +196,19 @@ function SaveAction() {
196
196
  ```
197
197
 
198
198
  Desktop notifications appear at the top right; mobile notifications use the available width with at least 16px side gutters and safe-area handling. Select options use full-row selected/hover backgrounds. Public behavior is demonstrated in Storybook and exercised at 375px and 1280px.
199
+ ### Optional motion policy
200
+
201
+ Motion defaults to `auto` and always respects the system's reduced-motion preference. Use `FactoMotionProvider` or `FactoTheme` to set `motion="none"` globally. Button, DialogContent, SheetContent, Toast and the motion primitives accept local overrides. An omitted value inherits; a local `auto` can override a global `none`, but never overrides reduced motion.
202
+
203
+ ```tsx
204
+ <FactoTheme motion="auto">
205
+ <Button loading={pending}>Continue</Button>
206
+ <StepTransition stepKey={step} motion="none">
207
+ {content}
208
+ </StepTransition>
209
+ </FactoTheme>
210
+ ```
211
+
212
+ `motion` controls playback; `motionVariant` continues to choose the existing overlay recipe. Turning motion off keeps loading, disabled state, dismissal and focus behavior intact. Shared primitives include `AnimatedDisclosure`, `AnimatedFeedback`, `ContentReveal`, `SelectionMotion` and `useKeyedListMotion`. They do not perform requests or own application state. See [motion guidance](dist/ai/references/motion.md) for composition and interruption checks.
213
+
214
+ Select is borderless by default. Use `<Select bordered options={options} ariaLabel="Choose an option" />` to enable a visible control border. Keyboard focus and error indicators remain available in both modes.
package/dist/ai/SKILL.md CHANGED
@@ -22,7 +22,8 @@ Read [ui-standard.md](references/ui-standard.md) for shared typography, weights,
22
22
  3. Read [integration.md](references/integration.md) for styles, font loading, framework constraints and version handling. Read [design.md](references/design.md) to retain the default Dashboard appearance or adapt a requested theme.
23
23
  4. Select components using [components.md](references/components.md). Search [api.d.ts](references/api.d.ts) for the exact component's props, and use installed declarations as the final authority. Read only relevant declarations. Do not invent exports, props, a global toast store, a data table or a chart API.
24
24
  5. For combined workflows (filters, async forms, nested Sheet/Dialog/Select, Toast), read [composition.md](references/composition.md). Adapt [AdoptionDemo.tsx](assets/AdoptionDemo.tsx) and [adoption.css](assets/adoption.css) only if useful. They are a runnable mock reference, not a replacement for existing business data or an entire application scaffold.
25
- 6. Verify the changed workflows with the app's typecheck/build and focused interaction checks. Inspect computed styles and representative narrow/wide layouts when a browser is available. Verify Inter actually loads for Latin text, theme overrides reach portals, and existing behavior remains intact. Report any unverified paths; building alone is not a visual audit.
25
+ 6. For optional motion, read [motion.md](references/motion.md). Default to `auto`, honor reduced motion, preserve behavior when disabled, and keep business timing outside animation completion.
26
+ 7. Verify the changed workflows with the app's typecheck/build and focused interaction checks. Inspect computed styles and representative narrow/wide layouts when a browser is available. Verify Inter actually loads for Latin text, theme overrides reach portals, and existing behavior remains intact. Report any unverified paths; building alone is not a visual audit.
26
27
 
27
28
  Keep Dashboard defaults unless the user requests another palette. Prefer public components and --facto-* tokens over copying package implementation CSS. Importing the package does not automatically restyle legacy HTML. The library has no runtime environment variables or business API credentials. Do not add those for UI adoption.
28
29
 
@@ -1,5 +1,5 @@
1
1
  import * as react from 'react';
2
- import { ImgHTMLAttributes, ReactNode, HTMLAttributes, MouseEventHandler, AnchorHTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, SVGProps, TextareaHTMLAttributes } from 'react';
2
+ import { ReactNode, HTMLAttributes, RefObject, ImgHTMLAttributes, MouseEventHandler, AnchorHTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, SVGProps, TextareaHTMLAttributes } from 'react';
3
3
  import * as PopoverPrimitive from '@radix-ui/react-popover';
4
4
  import * as MenuPrimitive from '@radix-ui/react-dropdown-menu';
5
5
  import * as TooltipPrimitive from '@radix-ui/react-tooltip';
@@ -9,6 +9,79 @@ import * as DialogPrimitive from '@radix-ui/react-dialog';
9
9
  import * as SwitchPrimitive from '@radix-ui/react-switch';
10
10
  import * as TabsPrimitive from '@radix-ui/react-tabs';
11
11
 
12
+ /** Auto enables motion while respecting the operating system's reduced-motion preference. */
13
+ type MotionMode = 'auto' | 'none';
14
+ /** Shared presentation timings in milliseconds, independent of application timing. */
15
+ declare const motionTokens: {
16
+ readonly duration: {
17
+ readonly feedback: 160;
18
+ readonly content: 180;
19
+ readonly surface: 220;
20
+ readonly overlay: 240;
21
+ };
22
+ readonly easing: {
23
+ readonly standard: "cubic-bezier(.22, 1, .36, 1)";
24
+ };
25
+ };
26
+ declare function useMotion(override?: MotionMode): {
27
+ motion: MotionMode;
28
+ reduced: boolean;
29
+ enabled: boolean;
30
+ };
31
+ /** Nest to override a section. The display-contents boundary adds no layout box. */
32
+ declare function FactoMotionProvider({ motion, children }: {
33
+ motion?: MotionMode;
34
+ children: ReactNode;
35
+ }): react.JSX.Element;
36
+
37
+ type MotionOverride = 'auto' | 'none';
38
+ interface StepTransitionProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
39
+ stepKey: string | number;
40
+ children: ReactNode;
41
+ motion?: MotionOverride;
42
+ }
43
+ /** Replaces step content immediately while coordinating the surrounding height. */
44
+ declare function StepTransition({ stepKey, children, motion, className, ...props }: StepTransitionProps): react.JSX.Element;
45
+ interface AnimatedDisclosureProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
46
+ open: boolean;
47
+ children: ReactNode;
48
+ motion?: MotionOverride;
49
+ }
50
+ /** Controlled region whose closed content is immediately removed from keyboard navigation. */
51
+ declare function AnimatedDisclosure({ open, children, motion, className, ...props }: AnimatedDisclosureProps): react.JSX.Element;
52
+ interface AnimatedFeedbackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
53
+ show: boolean;
54
+ children: ReactNode;
55
+ motion?: MotionOverride;
56
+ }
57
+ /** Controlled feedback presentation; consumer validation and alert semantics change synchronously. */
58
+ declare function AnimatedFeedback({ show, children, motion, className, role, ...props }: AnimatedFeedbackProps): react.JSX.Element;
59
+ interface ContentRevealProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
60
+ children: ReactNode;
61
+ ready?: boolean;
62
+ motion?: MotionOverride;
63
+ }
64
+ /** Reveals only when pending content becomes ready; later content updates remain still. */
65
+ declare function ContentReveal({ children, ready, motion, className, ...props }: ContentRevealProps): react.JSX.Element;
66
+
67
+ type ListMotionKey = string | number;
68
+ /**
69
+ * Applies FLIP movement to rows with a `data-list-motion-key` matching an item key.
70
+ * Rows removed by React are never retained for an exit animation.
71
+ */
72
+ declare function useKeyedListMotion<Key extends ListMotionKey>(rootRef: RefObject<HTMLElement | null>, itemKeys: readonly Key[], { motion }?: {
73
+ motion?: MotionMode;
74
+ }): void;
75
+ interface SelectionMotionProps extends HTMLAttributes<HTMLDivElement> {
76
+ /** Overrides the nearest Facto motion setting for this visual treatment. */
77
+ motion?: MotionMode;
78
+ }
79
+ /**
80
+ * Positions a decorative surface beneath the selected descendant. Selection and
81
+ * keyboard behavior remain the responsibility of the controls it contains.
82
+ */
83
+ declare function SelectionMotion({ motion, className, children, ...props }: SelectionMotionProps): react.JSX.Element;
84
+
12
85
  interface ListRowSlots {
13
86
  leading?: ReactNode;
14
87
  title: ReactNode;
@@ -101,6 +174,12 @@ interface OtpInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'def
101
174
  onValueChange: (value: string) => void;
102
175
  /** Number of visual code cells and the maximum accepted code length. */
103
176
  length?: number;
177
+ /** Adds a subtle midpoint gap for 6-digit (3-3) or 8-digit (4-4) readability. */
178
+ split?: boolean;
179
+ /** Accepts uppercase letters and digits instead of numeric digits only. */
180
+ alphanumeric?: boolean;
181
+ /** Displays confirmed accent styling once verification succeeds. */
182
+ verified?: boolean;
104
183
  /** Called once for each distinct complete value, after the controlled value updates. */
105
184
  onComplete?: (value: string) => void;
106
185
  /** Delay before `onComplete`, allowing the final digit to render before navigation. */
@@ -115,11 +194,11 @@ interface OtpInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'def
115
194
  containerClassName?: string;
116
195
  }
117
196
  /**
118
- * Accessible segmented one-time-code input backed by one native input so paste
119
- * and platform autofill work as expected. Authentication and verification stay
120
- * in the consuming application.
197
+ * Accessible segmented one-time-code input backed by one native input over
198
+ * 1:1 square visual cells so paste, platform autofill, and click-to-replace
199
+ * work natively. Authentication and verification stay in the consuming app.
121
200
  */
122
- declare function OtpInput({ value, onValueChange, length, onComplete, completionDelay, pending, pendingLabel, label, helperText, error, id, className, containerClassName, disabled, readOnly, onPaste, onFocus, onBlur, ...props }: OtpInputProps): react.JSX.Element;
201
+ declare function OtpInput({ value, onValueChange, length, split, alphanumeric, verified, onComplete, completionDelay, pending, pendingLabel, label, helperText, error, id, className, containerClassName, disabled, readOnly, onPaste, onFocus, onBlur, onSelect, onClick, ...props }: OtpInputProps): react.JSX.Element;
123
202
  interface ResendCodeButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
124
203
  /** UTC timestamp (milliseconds) or Date until another request may be sent. */
125
204
  deadline?: number | Date | null;
@@ -187,16 +266,211 @@ declare function NotificationsProvider({ children, duration, maxVisible, label,
187
266
  /** Returns the notification API for the nearest NotificationsProvider. */
188
267
  declare function useToast(): ToastApi;
189
268
 
269
+ interface AuthFlowShellProps extends HTMLAttributes<HTMLDivElement> {
270
+ /** Standalone quiet page canvas (`page`) or embedded column (`plain`). */
271
+ surface?: 'page' | 'plain';
272
+ /** Expands column width to 620px for multi-column selection steps. */
273
+ wide?: boolean;
274
+ /** Coordinates smooth height and content transitions across steps when provided. */
275
+ stepKey?: string | number;
276
+ /** Motion override forwarded to StepTransition (`auto` | `none`). */
277
+ motion?: MotionOverride;
278
+ brand?: ReactNode;
279
+ badge?: ReactNode;
280
+ children: ReactNode;
281
+ }
282
+ /** Shared focused column shell for verification, MFA, and onboarding flows. */
283
+ declare function AuthFlowShell({ surface, wide, stepKey, motion, brand, badge, children, className, ...props }: AuthFlowShellProps): react.JSX.Element;
284
+ interface StepProgressProps extends HTMLAttributes<HTMLDivElement> {
285
+ current: number;
286
+ total: number;
287
+ label?: ReactNode;
288
+ }
289
+ /** Minimalist segmented step progress bar for multi-step flows. */
290
+ declare function StepProgress({ current, total, label, className, ...props }: StepProgressProps): react.JSX.Element;
291
+ interface IdentityEchoPillProps extends HTMLAttributes<HTMLDivElement> {
292
+ value: string;
293
+ onEdit?: () => void;
294
+ editLabel?: ReactNode;
295
+ }
296
+ /** Displays the active verification target (such as an email address) with an optional edit trigger. */
297
+ declare function IdentityEchoPill({ value, onEdit, editLabel, className, ...props }: IdentityEchoPillProps): react.JSX.Element;
298
+ interface CopyableSecretKeyProps {
299
+ /** Raw secret value copied to the clipboard. */
300
+ value: string;
301
+ /** Optional formatted string shown to the user (defaults to `value`). */
302
+ displayValue?: string;
303
+ copyLabel?: ReactNode;
304
+ copiedLabel?: ReactNode;
305
+ onCopy?: (value: string) => void;
306
+ className?: string;
307
+ ariaLabel?: string;
308
+ }
309
+ /** Tactile monospace key bar for manual authenticator app enrollment. */
310
+ declare function CopyableSecretKey({ value, displayValue, copyLabel, copiedLabel, onCopy, className, ariaLabel, }: CopyableSecretKeyProps): react.JSX.Element;
311
+ interface EmailVerificationStepProps {
312
+ email: string;
313
+ code: string;
314
+ onCodeChange: (value: string) => void;
315
+ onSubmit?: (code: string) => void;
316
+ /** Optional inline email update callback; shows an Edit action when provided. */
317
+ onEmailChange?: (nextEmail: string) => void;
318
+ onBack?: () => void;
319
+ onResend?: () => void;
320
+ resendDeadline?: number | Date | null;
321
+ resendPending?: boolean;
322
+ step?: {
323
+ current: number;
324
+ total: number;
325
+ label?: ReactNode;
326
+ };
327
+ title?: ReactNode;
328
+ description?: ReactNode;
329
+ helperText?: ReactNode;
330
+ error?: ReactNode;
331
+ pending?: boolean;
332
+ verified?: boolean;
333
+ autoSubmit?: boolean;
334
+ length?: number;
335
+ alphanumeric?: boolean;
336
+ unreadCount?: number;
337
+ submitLabel?: ReactNode;
338
+ backLabel?: ReactNode;
339
+ className?: string;
340
+ }
341
+ /**
342
+ * Reusable email verification step ("Check your inbox") built on 1:1 square
343
+ * `OtpInput` and isolated `ResendCodeButton` so countdown ticks never steal focus.
344
+ */
345
+ declare function EmailVerificationStep({ email, code, onCodeChange, onSubmit, onEmailChange, onBack, onResend, resendDeadline, resendPending, step, title, description, helperText, error, pending, verified, autoSubmit, length, alphanumeric, unreadCount, submitLabel, backLabel, className, }: EmailVerificationStepProps): react.JSX.Element;
346
+ interface PasskeySetupCardProps {
347
+ step?: {
348
+ current: number;
349
+ total: number;
350
+ label?: ReactNode;
351
+ };
352
+ illustration?: ReactNode;
353
+ title?: ReactNode;
354
+ description?: ReactNode;
355
+ capabilities?: readonly ReactNode[];
356
+ ctaLabel?: ReactNode;
357
+ pendingLabel?: ReactNode;
358
+ pending?: boolean;
359
+ verified?: boolean;
360
+ verifiedMessage?: ReactNode;
361
+ error?: ReactNode;
362
+ onCreatePasskey: () => void;
363
+ onSwitchAlternative?: () => void;
364
+ alternativeLabel?: ReactNode;
365
+ className?: string;
366
+ }
367
+ /**
368
+ * Passkey-first MFA setup step. Keeps the quiet capability panel visually
369
+ * distinct from the 44px primary action below it.
370
+ */
371
+ declare function PasskeySetupCard({ step, illustration, title, description, capabilities, ctaLabel, pendingLabel, pending, verified, verifiedMessage, error, onCreatePasskey, onSwitchAlternative, alternativeLabel, className, }: PasskeySetupCardProps): react.JSX.Element;
372
+ interface TotpEmailFactorProps {
373
+ code: string;
374
+ onCodeChange: (value: string) => void;
375
+ onSend: () => void;
376
+ deadline?: number | Date | null;
377
+ sending?: boolean;
378
+ title?: ReactNode;
379
+ description?: ReactNode;
380
+ }
381
+ interface TotpEnrollmentCardProps {
382
+ step?: {
383
+ current: number;
384
+ total: number;
385
+ label?: ReactNode;
386
+ };
387
+ title?: ReactNode;
388
+ description?: ReactNode;
389
+ issuer: string;
390
+ accountLabel: string;
391
+ /** QR code element (e.g. rendered SVG or `<img>` from a data URL). */
392
+ qrCode: ReactNode;
393
+ manualKey: string;
394
+ displayManualKey?: string;
395
+ code: string;
396
+ onCodeChange: (value: string) => void;
397
+ onSubmit: (code: string) => void;
398
+ /** Optional secondary email OTP factor for high-risk TOTP enable/disable flows. */
399
+ emailFactor?: TotpEmailFactorProps;
400
+ error?: ReactNode;
401
+ pending?: boolean;
402
+ verified?: boolean;
403
+ submitLabel?: ReactNode;
404
+ onSwitchAlternative?: () => void;
405
+ alternativeLabel?: ReactNode;
406
+ className?: string;
407
+ }
408
+ /**
409
+ * Authenticator app (TOTP) enrollment card combining a bordered QR code,
410
+ * tactile copyable manual key, square 6-digit `OtpInput`, and optional dual-factor email code.
411
+ */
412
+ declare function TotpEnrollmentCard({ step, title, description, issuer, accountLabel, qrCode, manualKey, displayManualKey, code, onCodeChange, onSubmit, emailFactor, error, pending, verified, submitLabel, onSwitchAlternative, alternativeLabel, className, }: TotpEnrollmentCardProps): react.JSX.Element;
413
+ /** Formats recovery codes into a plain-text file payload for download. */
414
+ declare function formatRecoveryCodesText(codes: readonly string[], meta?: {
415
+ issuer?: string;
416
+ account?: string;
417
+ }): string;
418
+ interface RecoveryCodesStepProps {
419
+ codes: readonly string[];
420
+ /** Indices of already-consumed codes when rendered in account management mode. */
421
+ usedIndices?: readonly number[];
422
+ variant?: 'onboarding' | 'manage';
423
+ step?: {
424
+ current: number;
425
+ total: number;
426
+ label?: ReactNode;
427
+ };
428
+ title?: ReactNode;
429
+ description?: ReactNode;
430
+ confirmationLabel?: ReactNode;
431
+ continueLabel?: ReactNode;
432
+ regenerateLabel?: ReactNode;
433
+ onCopyAll?: (codes: readonly string[]) => void;
434
+ onDownload?: (codes: readonly string[]) => void;
435
+ onContinue?: () => void;
436
+ onRegenerate?: () => void;
437
+ className?: string;
438
+ }
439
+ /**
440
+ * Show-once recovery codes panel with 2-column monospace grid, grid-aligned
441
+ * 10px nested Copy/Download utility buttons, and explicit save confirmation gate.
442
+ */
443
+ declare function RecoveryCodesStep({ codes, usedIndices, variant, step, title, description, confirmationLabel, continueLabel, regenerateLabel, onCopyAll, onDownload, onContinue, onRegenerate, className, }: RecoveryCodesStepProps): react.JSX.Element;
444
+ interface SelectionCardOption {
445
+ value: string;
446
+ title: ReactNode;
447
+ description?: ReactNode;
448
+ meta?: ReactNode;
449
+ metaTone?: 'default' | 'accent';
450
+ icon?: ReactNode;
451
+ disabled?: boolean;
452
+ }
453
+ interface SelectionCardGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
454
+ options: readonly SelectionCardOption[];
455
+ value: string;
456
+ onValueChange: (value: string) => void;
457
+ columns?: 1 | 2;
458
+ ariaLabel: string;
459
+ }
460
+ /** Accessible radio-card selection group for role, workspace, or funding mode steps. */
461
+ declare function SelectionCardGroup({ options, value, onValueChange, columns, ariaLabel, className, ...props }: SelectionCardGroupProps): react.JSX.Element;
462
+
190
463
  type FactoThemeTokens = Partial<Record<`--facto-${string}`, string | number>>;
191
464
  type ThemeTokens = FactoThemeTokens;
192
465
  interface FactoThemeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
193
466
  /** Scoped overrides; unspecified tokens inherit the dashboard defaults or parent theme. */
467
+ motion?: MotionMode;
194
468
  tokens?: FactoThemeTokens;
195
469
  /** Inline styles take precedence over the tokens prop. */
196
470
  style?: CSSProperties & Partial<ThemeTokens>;
197
471
  }
198
472
  /** Scoped token container. Inline `--facto-*` values are forwarded to portalled overlays. */
199
- declare function FactoTheme({ className, tokens, style, ...props }: FactoThemeProps): react.JSX.Element;
473
+ declare function FactoTheme({ className, tokens, style, motion, ...props }: FactoThemeProps): react.JSX.Element;
200
474
  /** Shared decorative symbols; name the containing control, not the glyph. */
201
475
  type IconName = 'close' | 'arrowLeft' | 'check' | 'chevronDown' | 'chevronRight' | 'info' | 'warning' | 'plus' | 'chevronLeft' | 'copy' | 'search';
202
476
  interface IconProps extends SVGProps<SVGSVGElement> {
@@ -215,6 +489,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
215
489
  size?: ButtonSize;
216
490
  fullWidth?: boolean;
217
491
  /** Shows a non-interactive progress indicator and disables the control. */
492
+ motion?: MotionMode;
218
493
  loading?: boolean;
219
494
  leadingIcon?: ReactNode;
220
495
  trailingIcon?: ReactNode;
@@ -294,6 +569,8 @@ interface SelectProps {
294
569
  placeholder?: string;
295
570
  label?: ReactNode;
296
571
  error?: ReactNode;
572
+ /** Opt in to a visible control border; default is borderless. */
573
+ bordered?: boolean;
297
574
  disabled?: boolean;
298
575
  name?: string;
299
576
  id?: string;
@@ -302,7 +579,7 @@ interface SelectProps {
302
579
  className?: string;
303
580
  }
304
581
  /** Controlled or uncontrolled Radix select. Use `options` for stable value/label pairs. */
305
- declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
582
+ declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, bordered, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
306
583
  interface SwitchProps extends Omit<ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, 'children'> {
307
584
  label?: ReactNode;
308
585
  description?: ReactNode;
@@ -328,10 +605,11 @@ declare const DialogDescription: typeof DialogPrimitive.Description;
328
605
  type OverlayMotionVariant = 'auto' | 'bottom' | 'none';
329
606
  interface DialogContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
330
607
  size?: 'sm' | 'md';
608
+ motion?: MotionMode;
331
609
  motionVariant?: OverlayMotionVariant;
332
610
  }
333
611
  /** Focus-managed modal content. Place title and description inside for accessible announcements. */
334
- declare function DialogContent({ size, motionVariant, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
612
+ declare function DialogContent({ size, motionVariant, motion, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
335
613
  declare const Sheet: react.FC<DialogPrimitive.DialogProps>;
336
614
  declare const SheetTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
337
615
  declare const SheetClose: react.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
@@ -339,10 +617,11 @@ declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.D
339
617
  declare const SheetDescription: react.ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
340
618
  interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
341
619
  side?: 'center' | 'right' | 'bottom';
620
+ motion?: MotionMode;
342
621
  motionVariant?: OverlayMotionVariant;
343
622
  }
344
623
  /** Focus-managed side or mobile-bottom sheet. */
345
- declare function SheetContent({ side, motionVariant, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
624
+ declare function SheetContent({ side, motionVariant, motion, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
346
625
  interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
347
626
  width?: string | number;
348
627
  height?: string | number;
@@ -386,11 +665,12 @@ declare function TooltipContent({ variant, className, style, sideOffset, collisi
386
665
  /** Dashboard notifications default to 2.6 seconds. */
387
666
  declare function ToastProvider({ duration, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Provider>): react.JSX.Element;
388
667
  interface ToastProps extends ComponentPropsWithRef<typeof ToastPrimitive.Root> {
668
+ motion?: MotionMode;
389
669
  icon?: ReactNode;
390
670
  tone?: NoticeTone;
391
671
  }
392
672
  /** Controlled or uncontrolled notification. Render a ToastViewport inside the provider. */
393
- declare function Toast({ tone, icon, className, style, children, ...props }: ToastProps): react.JSX.Element;
673
+ declare function Toast({ tone, icon, className, style, motion, children, ...props }: ToastProps): react.JSX.Element;
394
674
  declare function ToastTitle({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Title>): react.JSX.Element;
395
675
  declare function ToastDescription({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Description>): react.JSX.Element;
396
676
  declare function ToastAction({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Action>): react.JSX.Element;
@@ -432,5 +712,5 @@ interface ListSkeletonProps extends HTMLAttributes<HTMLDivElement> {
432
712
  /** Loading placeholder only: consumers own the query and loading state. */
433
713
  declare function ListSkeleton({ rows, label, className, ...props }: ListSkeletonProps): react.JSX.Element;
434
714
 
435
- export { Avatar, Badge, Button, Card, Checkbox, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, Surface, Switch, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Widget, WidgetAction, WidgetAmount, WidgetHeader, WidgetKeyValue, WidgetList, WidgetRow, useToast };
436
- export type { AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };
715
+ export { AnimatedDisclosure, AnimatedFeedback, AuthFlowShell, Avatar, Badge, Button, Card, Checkbox, ContentReveal, CopyableSecretKey, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmailVerificationStep, EmptyState, EnhancedSearchField, ErrorState, FactoMotionProvider, FactoTheme, Field, FilterChip, Icon, IconButton, IdentityEchoPill, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, PasskeySetupCard, Popover, PopoverClose, PopoverContent, PopoverTrigger, RecoveryCodesStep, ResendCodeButton, SearchField, Select, SelectionCardGroup, SelectionMotion, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, StepProgress, StepTransition, Surface, Switch, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TotpEnrollmentCard, Widget, WidgetAction, WidgetAmount, WidgetHeader, WidgetKeyValue, WidgetList, WidgetRow, formatRecoveryCodesText, motionTokens, useKeyedListMotion, useMotion, useToast };
716
+ export type { AnimatedDisclosureProps, AnimatedFeedbackProps, AuthFlowShellProps, AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, ContentRevealProps, CopyableSecretKeyProps, DialogContentProps, EmailVerificationStepProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, IdentityEchoPillProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, MotionMode, MotionOverride, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, PasskeySetupCardProps, RecoveryCodesStepProps, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SelectionCardGroupProps, SelectionCardOption, SelectionMotionProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, StepProgressProps, StepTransitionProps, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, TotpEmailFactorProps, TotpEnrollmentCardProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };
@@ -1,13 +1,18 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "package": "@facto-to/design-system",
4
- "packageVersion": "0.1.0-beta.7",
4
+ "packageVersion": "0.1.0-beta.9",
5
5
  "exports": [
6
+ "AnimatedDisclosure",
7
+ "AnimatedFeedback",
8
+ "AuthFlowShell",
6
9
  "Avatar",
7
10
  "Badge",
8
11
  "Button",
9
12
  "Card",
10
13
  "Checkbox",
14
+ "ContentReveal",
15
+ "CopyableSecretKey",
11
16
  "DashboardGrid",
12
17
  "Dialog",
13
18
  "DialogClose",
@@ -20,14 +25,17 @@
20
25
  "DropdownMenuItem",
21
26
  "DropdownMenuSeparator",
22
27
  "DropdownMenuTrigger",
28
+ "EmailVerificationStep",
23
29
  "EmptyState",
24
30
  "EnhancedSearchField",
25
31
  "ErrorState",
32
+ "FactoMotionProvider",
26
33
  "FactoTheme",
27
34
  "Field",
28
35
  "FilterChip",
29
36
  "Icon",
30
37
  "IconButton",
38
+ "IdentityEchoPill",
31
39
  "ListGroup",
32
40
  "ListRow",
33
41
  "ListSkeleton",
@@ -38,13 +46,17 @@
38
46
  "Notice",
39
47
  "NotificationsProvider",
40
48
  "OtpInput",
49
+ "PasskeySetupCard",
41
50
  "Popover",
42
51
  "PopoverClose",
43
52
  "PopoverContent",
44
53
  "PopoverTrigger",
54
+ "RecoveryCodesStep",
45
55
  "ResendCodeButton",
46
56
  "SearchField",
47
57
  "Select",
58
+ "SelectionCardGroup",
59
+ "SelectionMotion",
48
60
  "Sheet",
49
61
  "SheetClose",
50
62
  "SheetContent",
@@ -54,6 +66,8 @@
54
66
  "Skeleton",
55
67
  "Stack",
56
68
  "StepChecklist",
69
+ "StepProgress",
70
+ "StepTransition",
57
71
  "Surface",
58
72
  "Switch",
59
73
  "Tabs",
@@ -73,6 +87,7 @@
73
87
  "TooltipContent",
74
88
  "TooltipProvider",
75
89
  "TooltipTrigger",
90
+ "TotpEnrollmentCard",
76
91
  "Widget",
77
92
  "WidgetAction",
78
93
  "WidgetAmount",
@@ -80,6 +95,10 @@
80
95
  "WidgetKeyValue",
81
96
  "WidgetList",
82
97
  "WidgetRow",
98
+ "formatRecoveryCodesText",
99
+ "motionTokens",
100
+ "useKeyedListMotion",
101
+ "useMotion",
83
102
  "useToast"
84
103
  ],
85
104
  "tokens": [
@@ -90,6 +109,7 @@
90
109
  "--facto-action-danger-hover",
91
110
  "--facto-action-danger-pressed",
92
111
  "--facto-action-disabled",
112
+ "--facto-action-disabled-border",
93
113
  "--facto-action-disabled-text",
94
114
  "--facto-action-link",
95
115
  "--facto-action-link-pressed",
@@ -100,6 +120,8 @@
100
120
  "--facto-action-secondary",
101
121
  "--facto-action-secondary-hover",
102
122
  "--facto-action-secondary-pressed",
123
+ "--facto-auth-canvas",
124
+ "--facto-badge-dot",
103
125
  "--facto-badge-padding",
104
126
  "--facto-button-danger-padding",
105
127
  "--facto-button-font-size",
@@ -153,6 +175,7 @@
153
175
  "--facto-line-height-heading-md",
154
176
  "--facto-line-height-heading-sm",
155
177
  "--facto-line-height-label",
178
+ "--facto-line-strong",
156
179
  "--facto-motion-overlay-backdrop-enter",
157
180
  "--facto-motion-overlay-bottom-distance",
158
181
  "--facto-motion-overlay-bottom-duration",
@@ -172,6 +195,7 @@
172
195
  "--facto-radius-danger",
173
196
  "--facto-radius-dialog",
174
197
  "--facto-radius-input",
198
+ "--facto-radius-nested-control",
175
199
  "--facto-radius-sheet",
176
200
  "--facto-radius-sheet-mobile",
177
201
  "--facto-search-placeholder",
@@ -201,6 +225,7 @@
201
225
  "--facto-switch-track-checked",
202
226
  "--facto-tabs-list-background",
203
227
  "--facto-text",
228
+ "--facto-text-secondary",
204
229
  "--facto-toast-default-description",
205
230
  "--facto-toast-default-foreground",
206
231
  "--facto-toast-desktop-reserve",
@@ -3,13 +3,14 @@
3
3
  See catalog.json for the exact runtime exports and api.d.ts for types. The catalog is generated, not a list of independent widgets: compound parts count separately. Search declarations for the selected export rather than reading all types.
4
4
 
5
5
  - Actions: Button (primary/secondary/danger/text; sm/md/lg), IconButton (ariaLabel required; 44px target), Icon (shared decorative close/arrowLeft/check/chevronDown/info/warning). Button does not implement asChild.
6
- - Forms: TextField, Textarea, SearchField (native events); EnhancedSearchField (string callback); Select (options + onValueChange); Checkbox and Switch (Radix checked callbacks).
6
+ - Forms: TextField, Textarea, SearchField (native events); EnhancedSearchField (string callback); Select (options + onValueChange; borderless by default, bordered={true} opts in); Checkbox and Switch (Radix checked callbacks).
7
7
  - Layout: Surface/Card, Stack (gap 1–6), DashboardGrid, Widget, WidgetHeader, WidgetList, WidgetRow, WidgetKeyValue, WidgetAmount, WidgetAction. WidgetAction accepts href for a link; inspect its union type.
8
8
  - Feedback: Badge (success/warning/danger/neutral), Notice (also info), EmptyState, Skeleton. Badge has no info tone. Notice and EmptyState require title, not just children.
9
9
  - Tabs: Tabs, TabsList, TabsTrigger, TabsContent; matching value strings, keep accessible tab labels.
10
10
  - Dialog: Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose. Sheet has corresponding six parts. ModalHeader/ModalFooter are optional stateless layout slots. DialogContent defaults to sm=400px; explicit md=580px is the wide legacy variant. Use trigger/close asChild to wrap a Button; supply title and description in content.
11
11
  - Tooltip: TooltipProvider, Tooltip, TooltipTrigger, TooltipContent. Trigger asChild with a focusable control; default compact dark tooltip, variant="content" for white expanded content. Provider delay 300ms.
12
12
  - Toast: ToastProvider, Toast, ToastTitle, ToastDescription, ToastAction, ToastClose, ToastViewport. App controls open/onOpenChange. Default duration 2600ms; desktop top/right 24px with maximum width 420px, mobile top 16px and full available width with 16px side gutters and safe-area insets; semantic status surface and matching text/icon. One viewport per group. ToastAction requires altText. No imperative global notification store is exported.
13
+ - Motion: FactoMotionProvider, useMotion, motionTokens, StepTransition, AnimatedDisclosure, AnimatedFeedback, ContentReveal, SelectionMotion, useKeyedListMotion. Read [motion.md](motion.md) for global/individual controls and application-state boundaries.
13
14
  - Theme: FactoTheme and FactoThemeTokens type. Defaults work without custom values; inline token overrides are forwarded to portals.
14
15
 
15
16
  There is no exported Table, DataTable, DatePicker, Chart, Sidebar, Form controller or router. Keep host implementations for these and apply scoped tokens, or choose a separate dependency only when the task needs it. Do not import internal dist files, copy source modules or claim shadcn-compatible props merely because the implementation uses Radix.
@@ -39,3 +40,16 @@ Use `NotificationsProvider` with `useToast()` for scoped notification state, ids
39
40
  Use `Popover` for contextual interactive content and `DropdownMenu` for actions. Both restore focus; Tooltip remains supplemental text. `ListRow` becomes an anchor with href or a button with onClick, otherwise a static row. Never nest a button in an interactive row. `ListGroup`, `Avatar`, `LogoStack`, `ErrorState`, `LoadingMore`, `StepChecklist` are generic presentation; keep business registries, routing and data fetching in the app.
40
41
 
41
42
  `FilterChip` exposes selected/aria-pressed; `ListSkeleton` exposes row count and an accessible loading label. `Field` requires inputId; give its native input the same id.
43
+
44
+ ## Auth and verification kit
45
+
46
+ Use the shared UI-only auth and verification components across login, onboarding, MFA enrollment, and account security screens so every surface inherits identical spacing, 1:1 square OTP cells, and 44px operate button proportions:
47
+
48
+ - `AuthFlowShell`: centered `380px` single-axis page canvas (`surface="page"`, `#fdfdfd`) or embedded column (`surface="plain"`), with `wide` (`620px`) for multi-column selection steps.
49
+ - `StepProgress`: minimalist 3px segmented step bar (`current`, `total`, `label`).
50
+ - `IdentityEchoPill` & `CopyableSecretKey`: read-only identity bar with optional inline edit action, and tactile monospace setup-key copy button.
51
+ - `OtpInput`: single native `<input autocomplete="one-time-code">` layered over 1:1 square visual cells (`aspect-ratio: 1 / 1`), supporting `split` (3-3 / 4-4 grouping), `alphanumeric`, `verified`, active-slot caret, and single-click digit replacement. Never build OTP inputs from multiple `<input maxlength="1">` fields.
52
+ - `EmailVerificationStep`: composes mail badge, `IdentityEchoPill` (with optional inline email editor), square `OtpInput`, 44px primary CTA (or `autoSubmit`), and isolated `ResendCodeButton` that preserves OTP input focus during countdowns.
53
+ - `PasskeySetupCard` & `TotpEnrollmentCard`: passkey-first hero with quiet capability panel and independent 44px primary CTA; TOTP QR + `CopyableSecretKey` + square `OtpInput` (plus optional `emailFactor` for dual-factor enrollment).
54
+ - `RecoveryCodesStep` & `formatRecoveryCodesText`: 2x4 monospace code grid, grid-aligned 10px nested-radius `Copy codes` / `Download .txt` toolbar, and explicit confirmation checkbox gate (plus `variant="manage"` for security settings).
55
+ - `SelectionCardGroup`: accessible `role="radiogroup"` selection cards for workspace, role, or mode choices.
@@ -7,7 +7,7 @@ Read version.json for the version used to generate this skill. Check the target
7
7
  For a new compatible project with no installed package:
8
8
 
9
9
  ```sh
10
- npm install --save-exact @facto-to/design-system@0.1.0-beta.7
10
+ npm install --save-exact @facto-to/design-system@0.1.0-beta.9
11
11
  ```
12
12
 
13
13
  React 19 and React DOM 19 must already be compatible with the host; do not reinstall or upgrade them blindly. No Tailwind, backend SDK, API key or runtime environment variable is required.
@@ -0,0 +1,31 @@
1
+ # Optional motion
2
+
3
+ Motion is presentation only. The application owns data requests, validation, selection, navigation and completion. Never wait for an animation to finish before applying application state.
4
+
5
+ `FactoMotionProvider` accepts `motion="auto"` (default) or `motion="none"`. `FactoTheme` accepts the same property. An omitted value inherits the parent. Nested providers and supported component properties override their parent. `auto` always respects the operating system's reduced-motion preference, including changes while the interface is open; it does not force animation.
6
+
7
+ ```tsx
8
+ <FactoTheme motion="auto">
9
+ <Button loading={pending}>Continue</Button>
10
+ <Dialog>
11
+ <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
12
+ <DialogContent motion="none">
13
+ <DialogTitle>Preferences</DialogTitle>
14
+ <DialogDescription>Update your display preferences.</DialogDescription>
15
+ </DialogContent>
16
+ </Dialog>
17
+ </FactoTheme>
18
+ ```
19
+
20
+ Use `motion` to enable/disable playback and existing `motionVariant` to choose an overlay's visual treatment. Portalled overlays and notifications inherit motion settings through React context. The provider renders a display-contents boundary; it should be placed in a flow-content container, not between structural table elements.
21
+
22
+ - `StepTransition`: supply a stable `stepKey`; keep dialog title, close control and shared structure outside the changing content. Do not key/remount the dialog itself. Content height and entry coordinate without holding the previous interactive step.
23
+ - `AnimatedDisclosure`: controlled `open`; connect the trigger with `aria-expanded` and `aria-controls`. Hidden content is inert and unavailable to assistive technology.
24
+ - `AnimatedFeedback`: controlled `show`; retain application error text as needed. The wrapper does not infer error state or initiate retries.
25
+ - `ContentReveal`: controlled `ready`; use a separate layout-matched skeleton until ready. Background refresh should retain existing content.
26
+ - `SelectionMotion`: decorative indicator for existing `aria-pressed` or `aria-selected` controls. Consumers retain keyboard handling and selection semantics.
27
+ - `useKeyedListMotion`: stable item keys and `data-list-motion-key` on rows; first render is static, new rows enter and remaining rows move. Removed rows leave the DOM immediately; the hook never delays a deletion.
28
+
29
+ Buttons remain disabled and expose busy state with motion off. Turning motion off must also cancel in-flight JavaScript animations. Focus restoration, dismissal, loading state and final content must work without animation events. Do not add visible changing loading copy just to explain a spinner; keep the original accessible action name.
30
+
31
+ Verify default, global off, local override, system reduced motion and live preference changes. Exercise portals, rapid next/back, long content, narrow layouts, keyboard focus, and interruption during exit. A browser emulation check does not certify physical mobile keyboard behavior.