@slipstream-ui/core 0.3.0 → 0.4.0

package/src/manifests/timeline.manifest.json

@@ -0,0 +1,69 @@
+{
+  "id": "timeline",
+  "name": "Timeline",
+  "tier": "molecule",
+  "description": "Vertical chronology for experience, activity and audit trails, built on an ordered list.",
+  "designIntent": "Chronologies communicate order. Rendering them as an ordered list keeps the sequence structural for assistive tech, while the connector rule and dots provide the visual rhythm.",
+  "props": [
+    {
+      "name": "items",
+      "type": "{ title: string; period?: string; description?: string; icon?: ReactNode; muted?: boolean }[]",
+      "required": true,
+      "description": "Ordered timeline entries."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Experience",
+      "code": "<Timeline\n  items={[\n    { title: 'Senior Engineer', period: '2023 — Present', description: 'Platform team' },\n    { title: 'Engineer', period: '2020 — 2023' },\n  ]}\n/>",
+      "description": "Period label, title and supporting line per entry."
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't reverse the DOM order for newest-first",
+      "explanation": "Reverse the array instead so reading order matches visual order.",
+      "example": "// Avoid: flex-col-reverse\n// Prefer: items={items.slice().reverse()}"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Sequence",
+      "implementation": "Ordered list semantics",
+      "userRequirements": "Keep entries in chronological order in the array"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Periods",
+      "guidelines": [
+        "Use a consistent format",
+        "State Present for ongoing"
+      ],
+      "goodExamples": [
+        "2023 — Present",
+        "Jan 2024"
+      ],
+      "badExamples": [
+        "Some time ago"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Card",
+      "relationship": "Often embedded in profile/about cards",
+      "example": "<Card><CardContent><Timeline items={roles} /></CardContent></Card>"
+    }
+  ],
+  "relatedComponents": [
+    "List",
+    "Card",
+    "Separator"
+  ],
+  "package": "@slipstream-ui/core",
+  "importPath": "@slipstream-ui/core",
+  "version": "0.1.0",
+  "sourceDir": "timeline",
+  "exportName": "Timeline"
+}

package/src/manifests/toast.manifest.json

@@ -2,47 +2,99 @@
   "id": "toast",
   "name": "Toast",
   "tier": "molecule",
-  "description": "Accessible app-level notifications announced through a polite live region, with auto-dismiss, stacking and optional actions",
-  "designIntent": "Applications need lightweight feedback that does not steal focus. Toasts render into a labelled polite live region so screen readers announce them, stack newest-first, auto-dismiss on a timer, and support one optional action (typically undo).",
+  "description": "Accessible notifications: tree-scoped provider/hook plus an imperative toast() API rendered by <Toaster />.",
+  "designIntent": "Toasts announce status changes without stealing focus. The provider/useToast pair covers tree-scoped usage; the module-level toast() + <Toaster /> covers event handlers and data layers where threading a hook is impossible (e.g. 1000+ call sites). A polite live region and auto-dismiss keep the queue quiet.",
   "props": [
     {
       "name": "title",
       "type": "string",
       "required": true,
-      "description": "Short heading announced with the toast"
+      "description": "Toast heading.",
+      "examples": [
+        "Saved",
+        "Upload failed"
+      ]
     },
     {
       "name": "description",
       "type": "string",
       "required": false,
-      "description": "Optional supporting detail"
+      "description": "Supporting line under the title."
+    },
+    {
+      "name": "variant",
+      "type": "'default' | 'success' | 'error' | 'warning' | 'info'",
+      "required": false,
+      "defaultValue": "default",
+      "description": "Status accent (dot + optional rich tint).",
+      "enum": [
+        "default",
+        "success",
+        "error",
+        "warning",
+        "info"
+      ],
+      "examples": [
+        "success",
+        "error"
+      ]
     },
     {
       "name": "action",
       "type": "{ label: string; onClick: () => void }",
       "required": false,
-      "description": "Optional inline action; invoking it dismisses the toast"
+      "description": "Single inline action; dismisses the toast after running."
     },
     {
       "name": "duration",
       "type": "number",
-      "defaultValue": 5000,
       "required": false,
-      "description": "Auto-dismiss delay in ms; 0 keeps the toast until dismissed",
-      "enum": ["0", "5000"],
-      "examples": [0, 3000, 5000]
+      "defaultValue": "5000",
+      "description": "Auto-dismiss delay in ms; 0 keeps the toast until dismissed."
+    },
+    {
+      "name": "position",
+      "type": "'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'",
+      "required": false,
+      "defaultValue": "bottom-right",
+      "description": "Toaster placement (Toaster component).",
+      "enum": [
+        "top-left",
+        "top-center",
+        "top-right",
+        "bottom-left",
+        "bottom-center",
+        "bottom-right"
+      ],
+      "examples": [
+        "top-right"
+      ]
+    },
+    {
+      "name": "richColors",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Tint the toast surface with its status color (Toaster component)."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Notifications",
+      "description": "Accessible name of the live region (Toaster component)."
     }
   ],
   "examples": [
     {
-      "title": "Basic toast with useToast",
-      "code": "'use client';\n\nimport { ToastProvider, useToast } from '@/components/slipstream/toast';\n\nfunction SaveButton() {\n  const { toast } = useToast();\n  return (\n    <button onClick={() => toast({ title: 'Saved', description: 'Your changes are live.' })}>\n      Save\n    </button>\n  );\n}\n\nexport function App() {\n  return (\n    <ToastProvider>\n      <SaveButton />\n    </ToastProvider>\n  );\n}",
-      "description": "Wrap your app in ToastProvider once; call toast() anywhere below it."
+      "title": "Imperative API",
+      "code": "import { Toaster, toast } from '@slipstream-ui/core';\n\n<Toaster position=\"bottom-right\" richColors />\n\ntoast.success('Saved', 'Your changes are live');\ntoast.error('Upload failed', 'Check your connection');\ntoast({ title: 'Heads up', duration: 0 });",
+      "description": "Fire from event handlers or data layers — no hook needed."
     },
     {
-      "title": "Undo action",
-      "code": "toast({\n  title: 'License revoked',\n  action: { label: 'Undo', onClick: restore },\n  duration: 0,\n});",
-      "description": "duration: 0 keeps the toast until the user acts or dismisses it."
+      "title": "Tree-scoped provider",
+      "code": "<ToastProvider>\n  <App />\n</ToastProvider>;\n\nconst { toast, dismiss } = useToast();\ntoast({ title: 'Saved' });",
+      "description": "Existing provider/hook pair for component-scoped usage."
     }
   ],
   "antiPatterns": [
@@ -53,29 +105,53 @@
   ],
   "accessibility": [
     {
-      "feature": "Screen reader announcements",
-      "implementation": "Each toast renders inside role=status (implicit aria-live=polite) within a labelled list container."
+      "feature": "Polite live region",
+      "implementation": "Each toast renders role=status inside a labelled list; announcements never steal focus",
+      "userRequirements": "Keep messages short and actionable"
     },
     {
-      "feature": "Keyboard dismiss",
-      "implementation": "Toast content is regular DOM; buttons inside toasts are reachable and activatable with the keyboard."
+      "feature": "Dismiss control",
+      "implementation": "Every toast has a labelled dismiss button (Dismiss <title>)",
+      "userRequirements": "Don't remove the dismiss button"
+    },
+    {
+      "feature": "Auto-dismiss timing",
+      "implementation": "5s default; duration 0 keeps sticky toasts",
+      "userRequirements": "Use duration 0 for errors that need a decision"
     }
   ],
   "contentGuidelines": [
     {
       "contentType": "toast title",
-      "guidelines": ["State what happened in past tense", "Keep under ~60 characters"],
-      "goodExamples": ["Saved", "License revoked"],
-      "badExamples": ["Oops!"]
+      "guidelines": [
+        "State what happened in past tense",
+        "Keep under ~60 characters"
+      ],
+      "goodExamples": [
+        "Saved",
+        "License revoked"
+      ],
+      "badExamples": [
+        "Oops!"
+      ]
     }
   ],
   "compositionRules": [
     {
-      "component": "Confirmation",
-      "relationship": "Use Confirmation for destructive actions before they happen; use Toast to report the result after."
+      "component": "Toaster",
+      "relationship": "Mount once near the app root next to your router; keep it outside transforms so fixed positioning is not affected",
+      "example": "<App><Toaster /></App>"
+    },
+    {
+      "component": "ToastProvider",
+      "relationship": "Use the provider/hook pair when the call site is inside the React tree",
+      "example": "<ToastProvider><App /></ToastProvider>"
     }
   ],
-  "relatedComponents": ["Confirmation", "Button"],
+  "relatedComponents": [
+    "Confirmation",
+    "Button"
+  ],
   "package": "@slipstream-ui/core",
   "importPath": "@slipstream-ui/core",
   "version": "0.0.1",