@ds-mo/ui 0.2.3 → 0.2.4

package/dist/r/toast.json

@@ -70,7 +70,7 @@
     },
     {
       "path": "src/components/Toast/Toast.tsx",
-      "content": "import React, { forwardRef, useEffect, useState, useCallback, useRef, useSyncExternalStore } from 'react';\nimport ReactDOM from 'react-dom';\nimport { cn } from '@/utils/cn';\nimport { Text } from '@/components/Text';\nimport { Surface } from '@/components/Surface';\nimport type { SurfaceIntent } from '@/components/Surface';\nimport styles from './Toast.module.css';\n\n/* ─── Toast Types ───────────────────────────────────────────────────────────── */\n\nexport type ToastIntent = 'neutral' | 'brand' | 'positive' | 'negative' | 'warning' | 'caution';\nexport type ToastPosition = 'top-center' | 'top-right' | 'bottom-center' | 'bottom-right';\n\nexport interface ToastData {\n  id: string;\n  message: string;\n  intent?: ToastIntent;\n  duration?: number;\n  onDismiss?: () => void;\n}\n\nexport interface ToastOptions {\n  message: string;\n  intent?: ToastIntent;\n  /** Auto-dismiss duration in ms. 0 = no auto-dismiss. Default 4000. */\n  duration?: number;\n  onDismiss?: () => void;\n}\n\n/* ─── Toast Store (external, framework-agnostic) ────────────────────────────── */\n\nlet toasts: ToastData[] = [];\nconst listeners = new Set<() => void>();\n\nfunction emit() {\n  listeners.forEach(fn => fn());\n}\n\nfunction getSnapshot(): ToastData[] {\n  return toasts;\n}\n\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  return () => { listeners.delete(listener); };\n}\n\nlet idCounter = 0;\n\nexport const toast = {\n  show(options: ToastOptions): string {\n    const id = `toast-${++idCounter}`;\n    toasts = [...toasts, { id, ...options }];\n    emit();\n    return id;\n  },\n  info(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'neutral', ...options });\n  },\n  success(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'positive', ...options });\n  },\n  error(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'negative', ...options });\n  },\n  warning(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'warning', ...options });\n  },\n  dismiss(id: string) {\n    toasts = toasts.filter(t => t.id !== id);\n    emit();\n  },\n  dismissAll() {\n    toasts = [];\n    emit();\n  },\n};\n\n/* ─── useToasts hook ────────────────────────────────────────────────────────── */\n\nexport function useToasts(): ToastData[] {\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/* ─── Single Toast ──────────────────────────────────────────────────────────── */\n\nconst INTENT_MAP: Record<ToastIntent, SurfaceIntent> = {\n  neutral: 'neutral',\n  brand: 'brand',\n  positive: 'positive',\n  negative: 'negative',\n  warning: 'warning',\n  caution: 'caution',\n};\n\ninterface ToastItemProps {\n  data: ToastData;\n}\n\nconst ToastItem: React.FC<ToastItemProps> = ({ data }) => {\n  const [exiting, setExiting] = useState(false);\n  const timerRef = useRef<ReturnType<typeof setTimeout>>();\n\n  const dismiss = useCallback(() => {\n    setExiting(true);\n    setTimeout(() => {\n      toast.dismiss(data.id);\n      data.onDismiss?.();\n    }, 200);\n  }, [data]);\n\n  useEffect(() => {\n    const duration = data.duration ?? 4000;\n    if (duration > 0) {\n      timerRef.current = setTimeout(dismiss, duration);\n    }\n    return () => { if (timerRef.current) clearTimeout(timerRef.current); };\n  }, [data.duration, dismiss]);\n\n  return (\n    <Surface\n      intent={INTENT_MAP[data.intent ?? 'neutral']}\n      contrast=\"bold\"\n      elevation=\"floating\"\n      radius=\"lg\"\n      className={cn(styles.toast, exiting && styles.toastExit)}\n      role=\"status\"\n      aria-live=\"polite\"\n    >\n      <Text variant=\"text-body-medium\" as=\"span\" color=\"inherit\">\n        {data.message}\n      </Text>\n      <button\n        type=\"button\"\n        className={styles.dismiss}\n        onClick={dismiss}\n        aria-label=\"Dismiss\"\n      >\n        &times;\n      </button>\n    </Surface>\n  );\n};\n\n/* ─── ToastContainer ────────────────────────────────────────────────────────── */\n\nexport interface ToastContainerProps {\n  /** Where to render toasts on screen. */\n  position?: ToastPosition;\n}\n\nexport const ToastContainer = forwardRef<HTMLDivElement, ToastContainerProps>(\n  ({ position = 'top-center' }, ref) => {\n    const items = useToasts();\n\n    if (typeof document === 'undefined') return null;\n\n    return ReactDOM.createPortal(\n      <div\n        ref={ref}\n        className={cn(styles.container, styles[positionClass(position)])}\n        aria-label=\"Notifications\"\n      >\n        {items.map(item => (\n          <ToastItem key={item.id} data={item} />\n        ))}\n      </div>,\n      document.body\n    );\n  }\n);\n\nToastContainer.displayName = 'ToastContainer';\n\nfunction positionClass(position: ToastPosition): string {\n  switch (position) {\n    case 'top-center': return 'topCenter';\n    case 'top-right': return 'topRight';\n    case 'bottom-center': return 'bottomCenter';\n    case 'bottom-right': return 'bottomRight';\n  }\n}\n",
+      "content": "import React, { forwardRef, useEffect, useState, useCallback, useRef, useSyncExternalStore } from 'react';\nimport ReactDOM from 'react-dom';\nimport { cn } from '@/utils/cn';\nimport { Text } from '@/components/Text';\nimport { Surface } from '@/components/Surface';\nimport type { SurfaceIntent } from '@/components/Surface';\nimport styles from './Toast.module.css';\n\n/* ─── Toast Types ───────────────────────────────────────────────────────────── */\n\nexport type ToastIntent = 'neutral' | 'brand' | 'positive' | 'negative' | 'warning' | 'caution';\nexport type ToastPosition = 'top-center' | 'top-right' | 'bottom-center' | 'bottom-right';\n\nexport interface ToastData {\n  id: string;\n  message: string;\n  intent?: ToastIntent;\n  duration?: number;\n  onDismiss?: () => void;\n}\n\nexport interface ToastOptions {\n  message: string;\n  intent?: ToastIntent;\n  /** Auto-dismiss duration in ms. 0 = no auto-dismiss. Default 4000. */\n  duration?: number;\n  onDismiss?: () => void;\n}\n\n/* ─── Toast Store (external, framework-agnostic) ────────────────────────────── */\n\nlet toasts: ToastData[] = [];\nconst listeners = new Set<() => void>();\n\nfunction emit() {\n  listeners.forEach(fn => fn());\n}\n\nfunction getSnapshot(): ToastData[] {\n  return toasts;\n}\n\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  return () => { listeners.delete(listener); };\n}\n\nlet idCounter = 0;\n\nexport const toast = {\n  show(options: ToastOptions): string {\n    const id = `toast-${++idCounter}`;\n    toasts = [...toasts, { id, ...options }];\n    emit();\n    return id;\n  },\n  info(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'neutral', ...options });\n  },\n  success(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'positive', ...options });\n  },\n  error(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'negative', ...options });\n  },\n  warning(message: string, options?: Omit<ToastOptions, 'message'>): string {\n    return toast.show({ message, intent: 'warning', ...options });\n  },\n  dismiss(id: string) {\n    toasts = toasts.filter(t => t.id !== id);\n    emit();\n  },\n  dismissAll() {\n    toasts = [];\n    emit();\n  },\n};\n\n/* ─── useToasts hook ────────────────────────────────────────────────────────── */\n\nexport function useToasts(): ToastData[] {\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/* ─── Single Toast ──────────────────────────────────────────────────────────── */\n\nconst INTENT_MAP: Record<ToastIntent, SurfaceIntent> = {\n  neutral: 'neutral',\n  brand: 'brand',\n  positive: 'positive',\n  negative: 'negative',\n  warning: 'warning',\n  caution: 'caution',\n};\n\ninterface ToastItemProps {\n  data: ToastData;\n}\n\nconst ToastItem: React.FC<ToastItemProps> = ({ data }) => {\n  const [exiting, setExiting] = useState(false);\n  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);\n\n  const dismiss = useCallback(() => {\n    setExiting(true);\n    setTimeout(() => {\n      toast.dismiss(data.id);\n      data.onDismiss?.();\n    }, 200);\n  }, [data]);\n\n  useEffect(() => {\n    const duration = data.duration ?? 4000;\n    if (duration > 0) {\n      timerRef.current = setTimeout(dismiss, duration);\n    }\n    return () => { if (timerRef.current) clearTimeout(timerRef.current); };\n  }, [data.duration, dismiss]);\n\n  return (\n    <Surface\n      intent={INTENT_MAP[data.intent ?? 'neutral']}\n      contrast=\"bold\"\n      elevation=\"floating\"\n      radius=\"lg\"\n      className={cn(styles.toast, exiting && styles.toastExit)}\n      role=\"status\"\n      aria-live=\"polite\"\n    >\n      <Text variant=\"text-body-medium\" as=\"span\" color=\"inherit\">\n        {data.message}\n      </Text>\n      <button\n        type=\"button\"\n        className={styles.dismiss}\n        onClick={dismiss}\n        aria-label=\"Dismiss\"\n      >\n        &times;\n      </button>\n    </Surface>\n  );\n};\n\n/* ─── ToastContainer ────────────────────────────────────────────────────────── */\n\nexport interface ToastContainerProps {\n  /** Where to render toasts on screen. */\n  position?: ToastPosition;\n}\n\nexport const ToastContainer = forwardRef<HTMLDivElement, ToastContainerProps>(\n  ({ position = 'top-center' }, ref) => {\n    const items = useToasts();\n\n    if (typeof document === 'undefined') return null;\n\n    return ReactDOM.createPortal(\n      <div\n        ref={ref}\n        className={cn(styles.container, styles[positionClass(position)])}\n        aria-label=\"Notifications\"\n      >\n        {items.map(item => (\n          <ToastItem key={item.id} data={item} />\n        ))}\n      </div>,\n      document.body\n    );\n  }\n);\n\nToastContainer.displayName = 'ToastContainer';\n\nfunction positionClass(position: ToastPosition): string {\n  switch (position) {\n    case 'top-center': return 'topCenter';\n    case 'top-right': return 'topRight';\n    case 'bottom-center': return 'bottomCenter';\n    case 'bottom-right': return 'bottomRight';\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-mo/ui",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "CompoMo — composable React UI components styled with TokoMo design tokens",
   "keywords": [
     "react",

package/src/components/Button/Button.mdx

@@ -0,0 +1,143 @@
+import { Meta, Title, Subtitle, Canvas, Controls, Primary } from '@storybook/addon-docs/blocks';
+import * as ButtonStories from './Button.stories';
+
+<Meta of={ButtonStories} />
+
+<Title />
+
+<Subtitle>
+  Buttons trigger actions. They are the primary way users commit to a decision —
+  saving a record, opening a dialog, navigating somewhere meaningful.
+</Subtitle>
+
+A button should make its purpose obvious from its label, its visual weight, and
+its position on the page. The right button in the right place is invisible — it
+just feels like the next step. The wrong button competes for attention and slows
+the user down.
+
+## Playground
+
+Use the controls below to explore every prop the component accepts. This is the
+fastest way to understand how `variant`, `intent`, `contrast`, and `elevation`
+combine.
+
+<Primary />
+
+<Controls />
+
+## When to use
+
+Reach for a button when the user needs to perform an **action** — submit a form,
+delete a record, open a panel, run a process. If the user is navigating between
+pages or sections, prefer a link instead. Buttons are for verbs; links are for
+nouns.
+
+A page should have **one** clearly dominant button. If two actions look equally
+important, the user has to stop and read both before deciding — which is exactly
+the moment of friction good hierarchy avoids.
+
+## Variants
+
+`primary` is filled and carries the strongest visual weight. Use it for the one
+action you most want the user to take on a given screen.
+
+`secondary` is a softer treatment for actions that matter but should not compete
+with the primary action. Use `elevation="none"` to get the ghost treatment for
+tertiary actions like cancel, dismiss, or inline controls.
+
+<Canvas of={ButtonStories.Variants} />
+
+> **Do** pair one `primary` with one or more `secondary` buttons in a form footer.
+>
+> **Don't** stack two `primary` buttons next to each other — only one action can
+> be the primary one.
+
+## Intent
+
+Intent communicates the **meaning** of the action through color. Most buttons
+should use `brand` (the default) or `neutral`. Reserve semantic intents for
+moments when the meaning genuinely matches.
+
+<Canvas of={ButtonStories.Intents} />
+
+- `brand` — the default for primary calls-to-action
+- `neutral` — for actions that should not draw color, like filters or toolbar controls
+- `negative` — for destructive actions (delete, remove, discard)
+- `positive` — for confirmations of a successful state, used sparingly
+- `warning` / `caution` — for actions that need a moment of pause
+- `ai` — reserved for AI-generated or AI-triggering actions
+- `none` — inverted styling for use on colored or dark surfaces
+
+> **Don't** use `negative` intent for a cancel button. Cancel is not destructive;
+> it is the absence of an action. Use `secondary` with no intent.
+
+## Sizes
+
+Pick a size from the surrounding density, not the importance of the action.
+Forms and dialogs use `md`. Compact toolbars and table rows use `sm` or `xs`.
+Hero sections and marketing surfaces can use `lg`.
+
+<Canvas of={ButtonStories.Sizes} />
+
+## Icons
+
+A leading icon can clarify a button's purpose at a glance — but only when the
+icon's meaning is unambiguous. If you have to think about which icon to pick,
+the label alone is doing a better job.
+
+<Canvas of={ButtonStories.IconAndLabel} />
+
+Icon-only buttons must always have an `aria-label`. Without it, screen readers
+announce nothing meaningful, and keyboard users lose all context.
+
+<Canvas of={ButtonStories.IconOnly} />
+
+## States
+
+Buttons have several states that communicate progress or availability:
+
+- `inactive` — the action is not currently available, but may become available
+- `loading` — the action is in flight; prevents double-submission
+- `rounded` — pill-shaped variant for filter chips and compact actions
+
+<Canvas of={ButtonStories.Loading} />
+
+<Canvas of={ButtonStories.Inactive} />
+
+> **Do** use `loading` for any async action that takes longer than ~200ms.
+> Without it, users will click again, often submitting twice.
+
+## Full width
+
+Use `fullWidth` inside narrow containers like mobile sheets, side panels, or
+form footers where the button should fill the available width. Avoid full-width
+buttons on wide desktop layouts — they read as banner CTAs and feel heavy.
+
+<Canvas of={ButtonStories.FullWidth} />
+
+## On colored surfaces
+
+When a button sits on a colored or dark surface, set the `background` prop so
+the button can adapt its contrast to remain legible. The `BackgroundContext`
+story below demonstrates every variant against every supported surface.
+
+<Canvas of={ButtonStories.BackgroundContext} />
+
+## Accessibility
+
+- Every button must have a discernible name — either visible text in `label` or
+  an `aria-label` for icon-only buttons.
+- The `inactive` state is **not** the same as the HTML `disabled` attribute.
+  `inactive` keeps the button focusable and announceable; truly disabled buttons
+  vanish from the tab order and frustrate users who can't tell why an action
+  isn't working.
+- Touch targets meet the 24×24 CSS pixel minimum at all sizes; `xs` is intended
+  for dense desktop UIs and should not be used on mobile.
+
+## Full reference matrix
+
+The matrix below renders every meaningful combination of `variant`, `intent`,
+`contrast`, `elevation`, `size`, and state on a single canvas. Use it as a
+visual regression reference when changing tokens or styles.
+
+<Canvas of={ButtonStories.Matrix} />