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

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;
@@ -191,12 +264,13 @@ type FactoThemeTokens = Partial<Record<`--facto-${string}`, string | number>>;
191
264
  type ThemeTokens = FactoThemeTokens;
192
265
  interface FactoThemeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
193
266
  /** Scoped overrides; unspecified tokens inherit the dashboard defaults or parent theme. */
267
+ motion?: MotionMode;
194
268
  tokens?: FactoThemeTokens;
195
269
  /** Inline styles take precedence over the tokens prop. */
196
270
  style?: CSSProperties & Partial<ThemeTokens>;
197
271
  }
198
272
  /** Scoped token container. Inline `--facto-*` values are forwarded to portalled overlays. */
199
- declare function FactoTheme({ className, tokens, style, ...props }: FactoThemeProps): react.JSX.Element;
273
+ declare function FactoTheme({ className, tokens, style, motion, ...props }: FactoThemeProps): react.JSX.Element;
200
274
  /** Shared decorative symbols; name the containing control, not the glyph. */
201
275
  type IconName = 'close' | 'arrowLeft' | 'check' | 'chevronDown' | 'chevronRight' | 'info' | 'warning' | 'plus' | 'chevronLeft' | 'copy' | 'search';
202
276
  interface IconProps extends SVGProps<SVGSVGElement> {
@@ -215,6 +289,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
215
289
  size?: ButtonSize;
216
290
  fullWidth?: boolean;
217
291
  /** Shows a non-interactive progress indicator and disables the control. */
292
+ motion?: MotionMode;
218
293
  loading?: boolean;
219
294
  leadingIcon?: ReactNode;
220
295
  trailingIcon?: ReactNode;
@@ -294,6 +369,8 @@ interface SelectProps {
294
369
  placeholder?: string;
295
370
  label?: ReactNode;
296
371
  error?: ReactNode;
372
+ /** Opt in to a visible control border; default is borderless. */
373
+ bordered?: boolean;
297
374
  disabled?: boolean;
298
375
  name?: string;
299
376
  id?: string;
@@ -302,7 +379,7 @@ interface SelectProps {
302
379
  className?: string;
303
380
  }
304
381
  /** 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;
382
+ declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, bordered, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
306
383
  interface SwitchProps extends Omit<ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, 'children'> {
307
384
  label?: ReactNode;
308
385
  description?: ReactNode;
@@ -328,10 +405,11 @@ declare const DialogDescription: typeof DialogPrimitive.Description;
328
405
  type OverlayMotionVariant = 'auto' | 'bottom' | 'none';
329
406
  interface DialogContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
330
407
  size?: 'sm' | 'md';
408
+ motion?: MotionMode;
331
409
  motionVariant?: OverlayMotionVariant;
332
410
  }
333
411
  /** 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;
412
+ declare function DialogContent({ size, motionVariant, motion, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
335
413
  declare const Sheet: react.FC<DialogPrimitive.DialogProps>;
336
414
  declare const SheetTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
337
415
  declare const SheetClose: react.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
@@ -339,10 +417,11 @@ declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.D
339
417
  declare const SheetDescription: react.ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
340
418
  interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
341
419
  side?: 'center' | 'right' | 'bottom';
420
+ motion?: MotionMode;
342
421
  motionVariant?: OverlayMotionVariant;
343
422
  }
344
423
  /** Focus-managed side or mobile-bottom sheet. */
345
- declare function SheetContent({ side, motionVariant, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
424
+ declare function SheetContent({ side, motionVariant, motion, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
346
425
  interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
347
426
  width?: string | number;
348
427
  height?: string | number;
@@ -386,11 +465,12 @@ declare function TooltipContent({ variant, className, style, sideOffset, collisi
386
465
  /** Dashboard notifications default to 2.6 seconds. */
387
466
  declare function ToastProvider({ duration, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Provider>): react.JSX.Element;
388
467
  interface ToastProps extends ComponentPropsWithRef<typeof ToastPrimitive.Root> {
468
+ motion?: MotionMode;
389
469
  icon?: ReactNode;
390
470
  tone?: NoticeTone;
391
471
  }
392
472
  /** Controlled or uncontrolled notification. Render a ToastViewport inside the provider. */
393
- declare function Toast({ tone, icon, className, style, children, ...props }: ToastProps): react.JSX.Element;
473
+ declare function Toast({ tone, icon, className, style, motion, children, ...props }: ToastProps): react.JSX.Element;
394
474
  declare function ToastTitle({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Title>): react.JSX.Element;
395
475
  declare function ToastDescription({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Description>): react.JSX.Element;
396
476
  declare function ToastAction({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Action>): react.JSX.Element;
@@ -432,5 +512,5 @@ interface ListSkeletonProps extends HTMLAttributes<HTMLDivElement> {
432
512
  /** Loading placeholder only: consumers own the query and loading state. */
433
513
  declare function ListSkeleton({ rows, label, className, ...props }: ListSkeletonProps): react.JSX.Element;
434
514
 
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 };
515
+ export { AnimatedDisclosure, AnimatedFeedback, Avatar, Badge, Button, Card, Checkbox, ContentReveal, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoMotionProvider, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, SelectionMotion, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, StepTransition, 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, motionTokens, useKeyedListMotion, useMotion, useToast };
516
+ export type { AnimatedDisclosureProps, AnimatedFeedbackProps, AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, ContentRevealProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, MotionMode, MotionOverride, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SelectionMotionProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, StepTransitionProps, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };
@@ -1,13 +1,16 @@
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.8",
5
5
  "exports": [
6
+ "AnimatedDisclosure",
7
+ "AnimatedFeedback",
6
8
  "Avatar",
7
9
  "Badge",
8
10
  "Button",
9
11
  "Card",
10
12
  "Checkbox",
13
+ "ContentReveal",
11
14
  "DashboardGrid",
12
15
  "Dialog",
13
16
  "DialogClose",
@@ -23,6 +26,7 @@
23
26
  "EmptyState",
24
27
  "EnhancedSearchField",
25
28
  "ErrorState",
29
+ "FactoMotionProvider",
26
30
  "FactoTheme",
27
31
  "Field",
28
32
  "FilterChip",
@@ -45,6 +49,7 @@
45
49
  "ResendCodeButton",
46
50
  "SearchField",
47
51
  "Select",
52
+ "SelectionMotion",
48
53
  "Sheet",
49
54
  "SheetClose",
50
55
  "SheetContent",
@@ -54,6 +59,7 @@
54
59
  "Skeleton",
55
60
  "Stack",
56
61
  "StepChecklist",
62
+ "StepTransition",
57
63
  "Surface",
58
64
  "Switch",
59
65
  "Tabs",
@@ -80,6 +86,9 @@
80
86
  "WidgetKeyValue",
81
87
  "WidgetList",
82
88
  "WidgetRow",
89
+ "motionTokens",
90
+ "useKeyedListMotion",
91
+ "useMotion",
83
92
  "useToast"
84
93
  ],
85
94
  "tokens": [
@@ -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.
@@ -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.8
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.
@@ -1,7 +1,7 @@
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.8",
5
5
  "peerDependencies": {
6
6
  "react": "^19.0.0",
7
7
  "react-dom": "^19.0.0"
@@ -15,6 +15,6 @@
15
15
  "scope": "Existing component baseline only; public standard 1.2.24 is a target, not a full adoption claim."
16
16
  }
17
17
  },
18
- "apiSha256": "315045b5fcd7259485085df7b3795228e9c947f2b9d6a81bf90847e087fb0426",
18
+ "apiSha256": "9a691d648e97a4088c1fba21c102bdbc14531e7985d620a201a6ef449cd884e9",
19
19
  "tokensSha256": "87694ef0c56c366f356f781ccc9860f390017f852726ddd3f29caf59545cdca9"
20
20
  }
package/dist/index.d.ts CHANGED
@@ -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;
@@ -191,12 +264,13 @@ type FactoThemeTokens = Partial<Record<`--facto-${string}`, string | number>>;
191
264
  type ThemeTokens = FactoThemeTokens;
192
265
  interface FactoThemeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
193
266
  /** Scoped overrides; unspecified tokens inherit the dashboard defaults or parent theme. */
267
+ motion?: MotionMode;
194
268
  tokens?: FactoThemeTokens;
195
269
  /** Inline styles take precedence over the tokens prop. */
196
270
  style?: CSSProperties & Partial<ThemeTokens>;
197
271
  }
198
272
  /** Scoped token container. Inline `--facto-*` values are forwarded to portalled overlays. */
199
- declare function FactoTheme({ className, tokens, style, ...props }: FactoThemeProps): react.JSX.Element;
273
+ declare function FactoTheme({ className, tokens, style, motion, ...props }: FactoThemeProps): react.JSX.Element;
200
274
  /** Shared decorative symbols; name the containing control, not the glyph. */
201
275
  type IconName = 'close' | 'arrowLeft' | 'check' | 'chevronDown' | 'chevronRight' | 'info' | 'warning' | 'plus' | 'chevronLeft' | 'copy' | 'search';
202
276
  interface IconProps extends SVGProps<SVGSVGElement> {
@@ -215,6 +289,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
215
289
  size?: ButtonSize;
216
290
  fullWidth?: boolean;
217
291
  /** Shows a non-interactive progress indicator and disables the control. */
292
+ motion?: MotionMode;
218
293
  loading?: boolean;
219
294
  leadingIcon?: ReactNode;
220
295
  trailingIcon?: ReactNode;
@@ -294,6 +369,8 @@ interface SelectProps {
294
369
  placeholder?: string;
295
370
  label?: ReactNode;
296
371
  error?: ReactNode;
372
+ /** Opt in to a visible control border; default is borderless. */
373
+ bordered?: boolean;
297
374
  disabled?: boolean;
298
375
  name?: string;
299
376
  id?: string;
@@ -302,7 +379,7 @@ interface SelectProps {
302
379
  className?: string;
303
380
  }
304
381
  /** 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;
382
+ declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, bordered, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
306
383
  interface SwitchProps extends Omit<ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, 'children'> {
307
384
  label?: ReactNode;
308
385
  description?: ReactNode;
@@ -328,10 +405,11 @@ declare const DialogDescription: typeof DialogPrimitive.Description;
328
405
  type OverlayMotionVariant = 'auto' | 'bottom' | 'none';
329
406
  interface DialogContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
330
407
  size?: 'sm' | 'md';
408
+ motion?: MotionMode;
331
409
  motionVariant?: OverlayMotionVariant;
332
410
  }
333
411
  /** 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;
412
+ declare function DialogContent({ size, motionVariant, motion, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
335
413
  declare const Sheet: react.FC<DialogPrimitive.DialogProps>;
336
414
  declare const SheetTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
337
415
  declare const SheetClose: react.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
@@ -339,10 +417,11 @@ declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.D
339
417
  declare const SheetDescription: react.ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
340
418
  interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
341
419
  side?: 'center' | 'right' | 'bottom';
420
+ motion?: MotionMode;
342
421
  motionVariant?: OverlayMotionVariant;
343
422
  }
344
423
  /** Focus-managed side or mobile-bottom sheet. */
345
- declare function SheetContent({ side, motionVariant, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
424
+ declare function SheetContent({ side, motionVariant, motion, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
346
425
  interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
347
426
  width?: string | number;
348
427
  height?: string | number;
@@ -386,11 +465,12 @@ declare function TooltipContent({ variant, className, style, sideOffset, collisi
386
465
  /** Dashboard notifications default to 2.6 seconds. */
387
466
  declare function ToastProvider({ duration, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Provider>): react.JSX.Element;
388
467
  interface ToastProps extends ComponentPropsWithRef<typeof ToastPrimitive.Root> {
468
+ motion?: MotionMode;
389
469
  icon?: ReactNode;
390
470
  tone?: NoticeTone;
391
471
  }
392
472
  /** Controlled or uncontrolled notification. Render a ToastViewport inside the provider. */
393
- declare function Toast({ tone, icon, className, style, children, ...props }: ToastProps): react.JSX.Element;
473
+ declare function Toast({ tone, icon, className, style, motion, children, ...props }: ToastProps): react.JSX.Element;
394
474
  declare function ToastTitle({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Title>): react.JSX.Element;
395
475
  declare function ToastDescription({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Description>): react.JSX.Element;
396
476
  declare function ToastAction({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Action>): react.JSX.Element;
@@ -432,5 +512,5 @@ interface ListSkeletonProps extends HTMLAttributes<HTMLDivElement> {
432
512
  /** Loading placeholder only: consumers own the query and loading state. */
433
513
  declare function ListSkeleton({ rows, label, className, ...props }: ListSkeletonProps): react.JSX.Element;
434
514
 
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 };
515
+ export { AnimatedDisclosure, AnimatedFeedback, Avatar, Badge, Button, Card, Checkbox, ContentReveal, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoMotionProvider, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, SelectionMotion, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, StepTransition, 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, motionTokens, useKeyedListMotion, useMotion, useToast };
516
+ export type { AnimatedDisclosureProps, AnimatedFeedbackProps, AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, ContentRevealProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, MotionMode, MotionOverride, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SelectionMotionProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, StepTransitionProps, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };